ooxml-ui 0.6.0 → 0.8.0

package/README.md

@@ -58,24 +58,29 @@ with an incompatible build of this package.
 
 ## Features: elements
 
-| Tag                                                   | Attributes / properties                                                                                                                           | Events (all bubble, composed)                                                             |
-| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| `office-ui-button`                                    | `label`, `icon`, `command`, `disabled`, `pressed`, `expanded`, `icon-only`, `variant="stacked"`, `keyshortcuts`                                   | `office-command` `{ command }`                                                            |
-| `office-ui-checkbox`, `office-ui-switch`              | `checked`, `disabled`, `value`, `aria-label`; form-associated                                                                                     | `input`, `change`                                                                         |
-| `office-ui-select`                                    | `options` `[{ value, label, disabled? }]`, `value`, `selectedIndex`, `disabled`                                                                   | `input`, `change`                                                                         |
-| `office-ui-ribbon-group`                              | `label`, `launcher` (dialog launcher command), `launcher-disabled`; default slot                                                                  | launcher: `office-command` `{ command }`                                                  |
-| `office-ui-ribbon-stack`                              | `orientation="horizontal"`; default slot (three-row column of small commands by default)                                                          | none                                                                                      |
-| `office-ui-menu-button` / `-menu-item`                | button: `label`, `icon`, `command` (split button), `variant`, `disabled`, `keyshortcuts`; item: `command`, `label`, `icon`, `disabled`, `checked` | item choice: `office-command` `{ command }`                                               |
-| `office-ui-toolbar`                                   | `aria-label`, `aria-orientation`; arrow-key focus movement                                                                                        | none                                                                                      |
-| `office-ui-dialog`                                    | `open`, `heading`, `dismissible="false"`, `show()`, `close()`; slots default, `footer`                                                            | `office-dialog-close` `{ reason }` (cancelable)                                           |
-| `office-ui-status-bar` / `-status-item`               | `label`, `value`, `interactive`, `id`                                                                                                             | `office-status-activate` `{ id }`                                                         |
-| `office-ui-zoom-slider`                               | `value` (percent), `min`, `max`, `step`, `disabled`, `fit` (fit button name), `label`                                                             | `input`, `change`; fit: `office-command` `{ command: 'zoom-fit' }`                        |
-| `office-ui-tab-strip`                                 | `tabs` `[{ id, label, title? }]`, `selected`, `label`, `previous-label`, `next-label`, `add-label`, `add-disabled`, `add-title`, `disabled`       | `office-tab-select` `{ id }` (cancelable); add: `office-command` `{ command: 'tab-add' }` |
-| `office-ui-context-menu` / `office-ui-menu-separator` | `label`; `openAt(x, y)`, `close()`, `open`; `office-ui-menu-item` and separator children                                                          | item choice: `office-command` `{ command }`                                               |
-| `office-ui-command-search`                            | `commands` `[{ id, label, keywords?, disabled?, title? }]`, `placeholder`, `label`, `limit` (Office's "Tell me what you want to do")              | choice: `office-command` `{ command }`                                                    |
-| `office-ui-presence`                                  | `participants`, `max`, `label`                                                                                                                    | `office-presence-select` `{ id }`                                                         |
-| `office-ui-smartart`                                  | `drawing` (core `DiagramDrawing`), `schemeColors`, `label`                                                                                        | `office-smartart-render` (render report)                                                  |
-| `office-ui-icon`                                      | `name`, `label`                                                                                                                                   | none                                                                                      |
+| Tag                                                   | Attributes / properties                                                                                                                            | Events (all bubble, composed)                                                             |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `office-ui-button`                                    | `label`, `icon`, `command`, `disabled`, `pressed`, `expanded`, `icon-only`, `variant="stacked"`, `keyshortcuts`                                    | `office-command` `{ command }`                                                            |
+| `office-ui-checkbox`, `office-ui-switch`              | `checked`, `disabled`, `value`, `aria-label`; form-associated                                                                                      | `input`, `change`                                                                         |
+| `office-ui-select`                                    | `options` `[{ value, label, disabled? }]`, `value`, `selectedIndex`, `disabled`                                                                    | `input`, `change`                                                                         |
+| `office-ui-ribbon-group`                              | `label`, `launcher` (dialog launcher command), `launcher-disabled`; default slot                                                                   | launcher: `office-command` `{ command }`                                                  |
+| `office-ui-ribbon-stack`                              | `orientation="horizontal"`; default slot (three-row column of small commands by default)                                                           | none                                                                                      |
+| `office-ui-menu-button` / `-menu-item`                | button: `label`, `icon`, `command` (split button), `variant`, `disabled`, `keyshortcuts`; item: `command`, `label`, `icon`, `disabled`, `checked`  | item choice: `office-command` `{ command }`                                               |
+| `office-ui-toolbar`                                   | `aria-label`, `aria-orientation`; arrow-key focus movement                                                                                         | none                                                                                      |
+| `office-ui-dialog`                                    | `open`, `heading`, `dismissible="false"`, `show()`, `close()`; slots default, `footer`                                                             | `office-dialog-close` `{ reason }` (cancelable)                                           |
+| `office-ui-status-bar` / `-status-item`               | `label`, `value`, `interactive`, `id`                                                                                                              | `office-status-activate` `{ id }`                                                         |
+| `office-ui-zoom-slider`                               | `value` (percent), `min`, `max`, `step`, `disabled`, `fit` (fit button name), `label`                                                              | `input`, `change`; fit: `office-command` `{ command: 'zoom-fit' }`                        |
+| `office-ui-tab-strip`                                 | `tabs` `[{ id, label, title? }]`, `selected`, `label`, `previous-label`, `next-label`, `add-label`, `add-disabled`, `add-title`, `disabled`        | `office-tab-select` `{ id }` (cancelable); add: `office-command` `{ command: 'tab-add' }` |
+| `office-ui-context-menu` / `office-ui-menu-separator` | `label`; `openAt(x, y)`, `close()`, `open`; `office-ui-menu-item` and separator children                                                           | item choice: `office-command` `{ command }`                                               |
+| `office-ui-command-search`                            | `commands` `[{ id, label, keywords?, description?, disabled?, title? }]`, `placeholder`, `label`, `limit` (Office's "Tell me what you want to do") | choice: `office-command` `{ command }`                                                    |
+| `office-ui-presence`                                  | `participants`, `max`, `label`                                                                                                                     | `office-presence-select` `{ id }`                                                         |
+| `office-ui-smartart`                                  | `drawing` (core `DiagramDrawing`), `schemeColors`, `label`                                                                                         | `office-smartart-render` (render report)                                                  |
+| `office-ui-icon`                                      | `name`, `label`                                                                                                                                    | none                                                                                      |
+
+`attachKeyTips(scope)` (from `ooxml-ui/controls`) adds Office KeyTips to any element or shadow
+root: press and release Alt to show badges on controls marked `data-keytip="H"`, type a badge to
+activate it, and use `data-keytip-panel` / `data-keytip-level` for a tab's second level. Escape
+steps back; disabled controls are dimmed and never run.
 
 Setting a property never emits an event; only user activation does. Controls honour
 `prefers-color-scheme`, `forced-colors: active` (system colours and a visible focus ring) and

package/dist/{chunk-RT6XKAM4.js → chunk-L5FYB6M7.js}

@@ -452,7 +452,10 @@ var defineCommandSearch = definer("office-ui-command-search", () => {
       const query = this.input.value.trim().toLowerCase();
       if (!query) return this.hide();
       const limit = Math.max(1, Number(this.getAttribute("limit")) || 8);
-      this.found = this.items.filter((item) => `${item.label} ${item.keywords ?? ""}`.toLowerCase().includes(query)).slice(0, limit);
+      const rank = (item) => (item.disabled ? 2 : 0) + (item.label.toLowerCase().startsWith(query) ? 0 : 1);
+      this.found = this.items.map((item, order) => ({ item, order })).filter(
+        ({ item }) => `${item.label} ${item.keywords ?? ""} ${item.description ?? ""}`.toLowerCase().includes(query)
+      ).sort((a, b) => rank(a.item) - rank(b.item) || a.order - b.order).map(({ item }) => item).slice(0, limit);
       this.active = this.found.findIndex((item) => !item.disabled);
       this.render();
       this.show();
@@ -480,11 +483,12 @@ var defineCommandSearch = definer("office-ui-command-search", () => {
           const label = doc.createElement("span");
           label.textContent = item.label;
           option.append(label);
-          if (item.disabled) {
-            option.setAttribute("aria-disabled", "true");
-            const reason = doc.createElement("small");
-            reason.textContent = item.title ?? "Not available";
-            option.append(reason);
+          if (item.disabled) option.setAttribute("aria-disabled", "true");
+          const detail = item.disabled ? item.title ?? "Not available" : item.description;
+          if (detail) {
+            const line = doc.createElement("small");
+            line.textContent = detail;
+            option.append(line);
           }
           return option;
         })
@@ -1728,6 +1732,140 @@ var defineZoomSlider = definer("office-ui-zoom-slider", () => {
   return OfficeUiZoomSlider;
 });
 
+// src/keytips.ts
+var BADGE_CSS = "position:fixed;inset:auto;margin:0;padding:0;border:0;background:transparent;overflow:visible;pointer-events:none";
+var TIP_CSS = 'position:fixed;transform:translate(-50%,-30%);min-width:14px;padding:1px 4px;border:1px solid #8a8886;border-radius:2px;background:#fff;color:#1f1f1f;font:600 11px/14px "Segoe UI",system-ui,sans-serif;text-align:center;box-shadow:0 1px 3px rgb(0 0 0 / 25%)';
+var isDisabled = (el) => el.hasAttribute("disabled") || el.getAttribute("aria-disabled") === "true";
+var visible = (el) => {
+  const box = el.getBoundingClientRect();
+  return box.width > 0 && box.height > 0;
+};
+function activate(el) {
+  const inner = el.shadowRoot?.querySelector(".main, button");
+  (inner ?? el).click();
+}
+function attachKeyTips(scope) {
+  const doc = (scope instanceof ShadowRoot ? scope.host : scope).ownerDocument;
+  const view = doc.defaultView;
+  const layer = doc.createElement("div");
+  layer.setAttribute("aria-hidden", "true");
+  layer.style.cssText = BADGE_CSS;
+  const topLayer = typeof layer.showPopover === "function";
+  if (topLayer) layer.setAttribute("popover", "manual");
+  else layer.hidden = true;
+  scope.append(layer);
+  let levels = [];
+  let typed = "";
+  let altAlone = false;
+  const tipsAt = (container) => [...(container ?? scope).querySelectorAll("[data-keytip]")].filter((el) => {
+    const owner = el.parentElement?.closest("[data-keytip-level]") ?? null;
+    return owner === container && visible(el);
+  });
+  const current = () => tipsAt(levels.at(-1) ?? null);
+  const render = () => {
+    if (!handle.active) return;
+    layer.replaceChildren(
+      ...current().map((el) => {
+        const box = el.getBoundingClientRect();
+        const tip = doc.createElement("span");
+        tip.textContent = el.dataset.keytip;
+        tip.style.cssText = `${TIP_CSS};left:${Math.round(box.left + box.width / 2)}px;top:${Math.round(box.bottom - 4)}px;opacity:${isDisabled(el) || typed && !el.dataset.keytip.startsWith(typed) ? "0.45" : "1"}`;
+        return tip;
+      })
+    );
+  };
+  const show = () => {
+    if (topLayer && !layer.matches(":popover-open")) layer.showPopover?.();
+    else layer.hidden = false;
+    render();
+  };
+  const stop = () => {
+    levels = [];
+    typed = "";
+    if (topLayer) {
+      try {
+        layer.hidePopover?.();
+      } catch {
+      }
+    } else layer.hidden = true;
+    layer.replaceChildren();
+    handle.active = false;
+  };
+  const start = () => {
+    levels = [];
+    typed = "";
+    handle.active = true;
+    show();
+  };
+  const choose = (el) => {
+    typed = "";
+    if (isDisabled(el)) return render();
+    const panel = el.dataset.keytipPanel;
+    activate(el);
+    const next = panel ? [...scope.querySelectorAll("[data-keytip-level]")].find((el2) => el2.id === panel) ?? null : null;
+    if (next) {
+      levels.push(next);
+      view?.requestAnimationFrame ? view.requestAnimationFrame(render) : render();
+    } else stop();
+  };
+  const onKeyDown = (event) => {
+    const key = event;
+    if (key.key === "Alt") {
+      altAlone = !key.ctrlKey && !key.metaKey && !key.shiftKey;
+      return;
+    }
+    altAlone = false;
+    if (!handle.active) return;
+    if (key.key === "Escape") {
+      key.preventDefault();
+      key.stopPropagation();
+      typed = "";
+      if (levels.length) {
+        levels.pop();
+        render();
+      } else stop();
+      return;
+    }
+    if (key.key.length !== 1 || key.ctrlKey || key.metaKey) return stop();
+    key.preventDefault();
+    key.stopPropagation();
+    typed += key.key.toUpperCase();
+    const candidates = current().filter((el) => el.dataset.keytip.toUpperCase().startsWith(typed));
+    const exact = candidates.find((el) => el.dataset.keytip.toUpperCase() === typed);
+    if (exact) choose(exact);
+    else if (!candidates.length) typed = "";
+    render();
+  };
+  const onKeyUp = (event) => {
+    const key = event;
+    if (key.key !== "Alt" || !altAlone) return;
+    altAlone = false;
+    key.preventDefault();
+    if (handle.active) stop();
+    else start();
+  };
+  const onPointer = () => {
+    if (handle.active) stop();
+  };
+  const target = scope;
+  target.addEventListener("keydown", onKeyDown, true);
+  target.addEventListener("keyup", onKeyUp, true);
+  target.addEventListener("pointerdown", onPointer, true);
+  view?.addEventListener("blur", onPointer);
+  const handle = {
+    active: false,
+    dispose() {
+      stop();
+      target.removeEventListener("keydown", onKeyDown, true);
+      target.removeEventListener("keyup", onKeyUp, true);
+      target.removeEventListener("pointerdown", onPointer, true);
+      view?.removeEventListener("blur", onPointer);
+      layer.remove();
+    }
+  };
+  return handle;
+}
+
 // src/controls.ts
 var CONTROL_DEFINERS = [
   defineIcon,
@@ -1753,4 +1891,4 @@ function registerControls(registry) {
   for (const define of CONTROL_DEFINERS) define(registry);
 }
 
-export { CONTROL_DEFINERS, defineButton, defineCheckbox, defineCommandSearch, defineContextMenu, defineDialog, defineMenuButton, defineMenuItem, defineMenuSeparator, defineRibbonGroup, defineRibbonStack, defineSelect, defineStatusBar, defineStatusItem, defineSwitch, defineTabStrip, defineToolbar, defineZoomSlider, registerControls };
+export { CONTROL_DEFINERS, attachKeyTips, defineButton, defineCheckbox, defineCommandSearch, defineContextMenu, defineDialog, defineMenuButton, defineMenuItem, defineMenuSeparator, defineRibbonGroup, defineRibbonStack, defineSelect, defineStatusBar, defineStatusItem, defineSwitch, defineTabStrip, defineToolbar, defineZoomSlider, registerControls };

package/dist/command-search.d.ts

@@ -3,6 +3,8 @@ export interface OfficeSearchCommand {
     id: string;
     label: string;
     keywords?: string;
+    /** Where the command lives, shown under the label (for example "Home › Paragraph"). */
+    description?: string;
     disabled?: boolean;
     title?: string;
 }

package/dist/controls.d.ts

@@ -17,6 +17,7 @@ export type { OfficeSelectOption } from './select.js';
 export type { OfficeStatusActivateEvent } from './status-bar.js';
 export type { OfficeTab, OfficeTabSelectEvent } from './tab-strip.js';
 export type { OfficeSearchCommand } from './command-search.js';
+export { attachKeyTips, type KeyTipsHandle } from './keytips.js';
 /** Every control of this entry. */
 export declare const CONTROL_DEFINERS: readonly [import("./registry.js").Definer, import("./registry.js").Definer, import("./registry.js").Definer, import("./registry.js").Definer, import("./registry.js").Definer, import("./registry.js").Definer, import("./registry.js").Definer, import("./registry.js").Definer, import("./registry.js").Definer, import("./registry.js").Definer, import("./registry.js").Definer, import("./registry.js").Definer, import("./registry.js").Definer, import("./registry.js").Definer, import("./registry.js").Definer, import("./registry.js").Definer, import("./registry.js").Definer, import("./registry.js").Definer];
 /** Idempotent, SSR-safe (no-op without a DOM). */

package/dist/controls.js

@@ -1,3 +1,3 @@
-export { CONTROL_DEFINERS, defineButton, defineCheckbox, defineCommandSearch, defineContextMenu, defineDialog, defineMenuButton, defineMenuItem, defineMenuSeparator, defineRibbonGroup, defineRibbonStack, defineSelect, defineStatusBar, defineStatusItem, defineSwitch, defineTabStrip, defineToolbar, defineZoomSlider, registerControls } from './chunk-RT6XKAM4.js';
+export { CONTROL_DEFINERS, attachKeyTips, defineButton, defineCheckbox, defineCommandSearch, defineContextMenu, defineDialog, defineMenuButton, defineMenuItem, defineMenuSeparator, defineRibbonGroup, defineRibbonStack, defineSelect, defineStatusBar, defineStatusItem, defineSwitch, defineTabStrip, defineToolbar, defineZoomSlider, registerControls } from './chunk-L5FYB6M7.js';
 export { defineIcon } from './chunk-PCSUQPMC.js';
 import './chunk-EY266IK3.js';

package/dist/index.js

@@ -1,7 +1,7 @@
 import { installOfficeUiTheme } from './chunk-H4KFVIGT.js';
 export { THEME_CSS, THEME_STYLE_ID, installOfficeUiTheme } from './chunk-H4KFVIGT.js';
-import { registerControls } from './chunk-RT6XKAM4.js';
-export { CONTROL_DEFINERS, defineButton, defineCheckbox, defineCommandSearch, defineContextMenu, defineDialog, defineMenuButton, defineMenuItem, defineMenuSeparator, defineRibbonGroup, defineRibbonStack, defineSelect, defineStatusBar, defineStatusItem, defineSwitch, defineTabStrip, defineToolbar, defineZoomSlider, registerControls } from './chunk-RT6XKAM4.js';
+import { registerControls } from './chunk-L5FYB6M7.js';
+export { CONTROL_DEFINERS, attachKeyTips, defineButton, defineCheckbox, defineCommandSearch, defineContextMenu, defineDialog, defineMenuButton, defineMenuItem, defineMenuSeparator, defineRibbonGroup, defineRibbonStack, defineSelect, defineStatusBar, defineStatusItem, defineSwitch, defineTabStrip, defineToolbar, defineZoomSlider, registerControls } from './chunk-L5FYB6M7.js';
 export { ICON_CSS, createIconSvg, defineIcon, getIcon, listIcons, paintIcon, registerIcon } from './chunk-PCSUQPMC.js';
 import { definePresence } from './chunk-RLPL7Q6J.js';
 export { definePresence, initialsOf, participantsFromAwareness } from './chunk-RLPL7Q6J.js';

package/dist/keytips.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Office KeyTips: press and release Alt to show letter badges on ribbon controls, then type a
+ * badge to activate it. Products annotate controls only:
+ * - `data-keytip="H"` marks a control (one or two characters);
+ * - `data-keytip-panel="home-panel"` on a control (a ribbon tab) makes the controls inside the
+ *   element with that id the next level after it is activated.
+ * First-level tips are those not inside any `[data-keytip-level]` container; a panel element
+ * carries `data-keytip-level` so its tips only appear after its tab. Escape steps back a level;
+ * Alt, a click or focus leaving the scope exits. Disabled controls show dimmed and never run.
+ * Badges render in a `popover` top layer, so containment and overflow never misplace them.
+ */
+export interface KeyTipsHandle {
+    /** Whether badges are currently shown. */
+    readonly active: boolean;
+    dispose(): void;
+}
+type Root = ShadowRoot | HTMLElement;
+export declare function attachKeyTips(scope: Root): KeyTipsHandle;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ooxml-ui",
-	"version": "0.6.0",
+	"version": "0.8.0",
 	"description": "Shared, format-neutral web components and styles for the Office viewers (Word, PowerPoint, Excel)",
 	"keywords": [
 		"custom-elements",