ooxml-ui 0.7.0 → 0.8.0

package/README.md

@@ -77,6 +77,11 @@ with an incompatible build of this package.
 | `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
 coarse pointers (44px targets through `--office-target-size`). Tokens are the `--office-*`

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

@@ -1732,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,
@@ -1757,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/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-LCHYMVBZ.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-LCHYMVBZ.js';
-export { CONTROL_DEFINERS, defineButton, defineCheckbox, defineCommandSearch, defineContextMenu, defineDialog, defineMenuButton, defineMenuItem, defineMenuSeparator, defineRibbonGroup, defineRibbonStack, defineSelect, defineStatusBar, defineStatusItem, defineSwitch, defineTabStrip, defineToolbar, defineZoomSlider, registerControls } from './chunk-LCHYMVBZ.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.7.0",
+	"version": "0.8.0",
 	"description": "Shared, format-neutral web components and styles for the Office viewers (Word, PowerPoint, Excel)",
 	"keywords": [
 		"custom-elements",