@jackuait/blok 0.10.2 → 0.10.4

package/src/components/utils/key-icon.ts

@@ -0,0 +1,187 @@
+/**
+ * Utilities for rendering keyboard shortcut keys as inline SVG icons.
+ *
+ * Each key token is wrapped in a minimal inline SVG that renders the Unicode
+ * glyph as SVG <text>. No borders, no boxes — visually identical to plain
+ * Unicode text, but each symbol is a proper SVG element.
+ *
+ * The result matches the compact Mac-style shortcut display:
+ *   ⌘⌃L   ⌘D   ⌘⇧P   Del
+ *
+ * Usage:
+ *   element.innerHTML = makeShortcutHtml('⌘ + B');
+ */
+
+/**
+ * Canonical Unicode glyph for each key name.
+ * All modifier symbols and common key names are covered.
+ */
+const KEY_LABEL_MAP: Record<string, string> = {
+  '⌘': '⌘',
+  '⇧': '⇧',
+  '⌥': '⌥',
+  '⌃': '⌃',
+  '⌫': '⌫',
+  '⏎': '⏎',
+  '⎋': '⎋',
+  '␡': '⌦',
+  '↑': '↑',
+  '↓': '↓',
+  '←': '←',
+  '→': '→',
+  'ctrl': '⌃',
+  'alt': '⌥',
+  'shift': '⇧',
+  'enter': '↵',
+  'backspace': '⌫',
+  'escape': '⎋',
+  'esc': '⎋',
+  'delete': '⌦',
+  'del': 'Del',
+  'tab': '⇥',
+  'ins': 'Ins',
+  'win': '⊞',
+};
+
+/**
+ * Resolves a raw token string to its canonical display glyph.
+ */
+function resolveLabel(token: string): string {
+  const trimmed = token.trim();
+
+  return KEY_LABEL_MAP[trimmed.toLowerCase()] ?? KEY_LABEL_MAP[trimmed] ?? trimmed;
+}
+
+/**
+ * Splits a shortcut segment into individual key tokens.
+ * Handles concatenated modifier symbols like "⌃⌘L" → ['⌃', '⌘', 'L'].
+ */
+function tokenizeSegment(segment: string): string[] {
+  const modifierPattern = /([⌘⇧⌥⌃⌫⏎⎋⌦↑↓←→↵⇥])|([^⌘⇧⌥⌃⌫⏎⎋⌦↑↓←→↵⇥]+)/gu;
+  const tokens: string[] = [];
+
+  for (const match of segment.matchAll(modifierPattern)) {
+    const token = match[0].trim();
+
+    if (token) {
+      tokens.push(token);
+    }
+  }
+
+  return tokens;
+}
+
+/**
+ * Renders a single key glyph as an inline SVG <text> element.
+ * No border, no background — just the Unicode character as SVG.
+ * Font size and width adapt to single-char symbols vs multi-char labels.
+ */
+function makeKeySvg(label: string): string {
+  const isSymbol = label.length === 1;
+  // Symbols (⌘, ⇧, …) are wider glyphs; short text (Del, Ins) is narrower per-char
+  const fontSize = isSymbol ? 13 : 11;
+  const charWidth = isSymbol ? 13 : 7.5;
+  const w = Math.ceil(label.length * charWidth);
+  const h = 16;
+
+  return (
+    `<svg xmlns="http://www.w3.org/2000/svg"` +
+    ` width="${w}" height="${h}"` +
+    ` viewBox="0 0 ${w} ${h}"` +
+    ` style="display:inline-block;vertical-align:middle;flex-shrink:0"` +
+    ` aria-hidden="true">` +
+    `<text` +
+    ` x="${w / 2}"` +
+    ` y="${h / 2 + 1}"` +
+    ` text-anchor="middle"` +
+    ` dominant-baseline="middle"` +
+    ` font-family="-apple-system,BlinkMacSystemFont,'SF Pro Text','Helvetica Neue',sans-serif"` +
+    ` font-size="${fontSize}"` +
+    ` font-weight="400"` +
+    ` fill="currentColor"` +
+    `>${label}</text>` +
+    `</svg>`
+  );
+}
+
+/**
+ * Converts a beautified shortcut string (e.g. "⌘ + B" or "⌃⌘L") into an
+ * HTML string of inline SVG glyph elements, tightly concatenated with no
+ * separator — matching the compact Mac shortcut display style.
+ *
+ * Accepts the output of `beautifyShortcut()` which uses " + " as separator.
+ */
+export function makeShortcutHtml(shortcut: string): string {
+  const tokens = shortcut
+    .split(' + ')
+    .flatMap(tokenizeSegment);
+
+  if (tokens.length === 0) {
+    return shortcut;
+  }
+
+  const svgs = tokens.map((token) => makeKeySvg(resolveLabel(token)));
+
+  return `<span style="display:inline-flex;align-items:center;line-height:1">${svgs.join('')}</span>`;
+}
+
+/**
+ * Maps Unicode glyphs and short labels back to full English key names
+ * for use in human-readable tooltip descriptions.
+ */
+const READABLE_KEY_MAP: Record<string, string> = {
+  '⌘': 'Command',
+  '⇧': 'Shift',
+  '⌥': 'Option',
+  '⌃': 'Control',
+  '⌫': 'Backspace',
+  '⌦': 'Delete',
+  '⏎': 'Return',
+  '↵': 'Return',
+  '⎋': 'Escape',
+  '⇥': 'Tab',
+  '↑': 'Up',
+  '↓': 'Down',
+  '←': 'Left',
+  '→': 'Right',
+  'del': 'Delete',
+  'ins': 'Insert',
+  '⊞': 'Win',
+};
+
+/**
+ * Converts a shortcut string (e.g. "⌃⌘L" or "⌘ + C") into a human-readable
+ * description like "Control+Command+L" or "Command+C".
+ *
+ * Each token is expanded to its full English key name. Plain letter/number
+ * tokens are uppercased. Unknown glyphs are passed through as-is.
+ */
+export function shortcutToReadable(shortcut: string): string {
+  const tokens = shortcut
+    .split(' + ')
+    .flatMap(tokenizeSegment);
+
+  if (tokens.length === 0) {
+    return shortcut;
+  }
+
+  return tokens
+    .map((token) => {
+      const trimmed = token.trim();
+      const lower = trimmed.toLowerCase();
+
+      return READABLE_KEY_MAP[trimmed] ?? READABLE_KEY_MAP[lower] ?? trimmed.toUpperCase();
+    })
+    .join('+');
+}
+
+/**
+ * Creates a DOM element containing the SVG glyph icons for a shortcut.
+ */
+export function makeShortcutElement(shortcut: string): HTMLElement {
+  const el = document.createElement('span');
+
+  el.innerHTML = makeShortcutHtml(shortcut);
+
+  return el.firstElementChild as HTMLElement ?? el;
+}

package/src/components/utils/popover/components/hint/hint.ts

@@ -1,4 +1,5 @@
 import { Dom } from '../../../../dom';
+import { makeShortcutHtml } from '../../../key-icon';
 
 import { css } from './hint.const';
 
@@ -33,7 +34,8 @@ export class Hint {
     this.nodes.root.appendChild(this.nodes.title);
 
     if (params.description !== undefined) {
-      this.nodes.description = Dom.make('div', css.description, { textContent: params.description });
+      this.nodes.description = Dom.make('div', css.description);
+      this.nodes.description.innerHTML = makeShortcutHtml(params.description);
 
       this.nodes.root.appendChild(this.nodes.description);
     }

package/src/components/utils/popover/components/popover-item/popover-item-default/popover-item-default.ts

@@ -1,5 +1,7 @@
 import { DATA_ATTR } from '../../../../../constants/data-attributes';
 import { IconChevronRight } from '../../../../../icons';
+import { makeShortcutHtml, shortcutToReadable } from '../../../../key-icon';
+import { onHover } from '../../../../tooltip';
 import { twMerge } from '../../../../tw';
 import { PopoverItem } from '../popover-item';
 
@@ -272,13 +274,22 @@ export class PopoverItemDefault extends PopoverItem {
     if (params.secondaryLabel) {
       const secondaryEl = document.createElement('div');
 
-      secondaryEl.className = 'ml-auto shrink-0 flex items-center whitespace-nowrap pl-20 font-mono text-[13px] tracking-wide text-text-secondary/60';
+      secondaryEl.className = 'ml-auto shrink-0 inline-flex items-center whitespace-nowrap pl-20 leading-none text-text-secondary/60';
       secondaryEl.setAttribute(DATA_ATTR.popoverItemSecondaryTitle, '');
       secondaryEl.setAttribute('data-blok-testid', 'popover-item-secondary-title');
-      secondaryEl.textContent = params.secondaryLabel;
+      secondaryEl.innerHTML = makeShortcutHtml(params.secondaryLabel);
 
       root.appendChild(secondaryEl);
       this.nodes.secondaryLabelEl = secondaryEl;
+
+      if (params.title !== undefined) {
+        // Anchor tooltip to the inner SVG span (the visible glyphs), not the
+        // outer container which has large left padding — so the tooltip centers
+        // directly over the shortcut keys rather than over the padded div.
+        const glyphSpan = (secondaryEl.firstElementChild ?? secondaryEl) as HTMLElement;
+
+        onHover(glyphSpan, shortcutToReadable(params.secondaryLabel), { placement: 'top' });
+      }
     }
 
     // Trailing icon (right-side indicator, e.g. checkmark)
@@ -552,8 +563,10 @@ export class PopoverItemDefault extends PopoverItem {
       return;
     }
 
-    this.nodes.secondaryLabelEl.textContent = this.params.secondaryLabel ?? '';
-    this.nodes.secondaryLabelEl.style.display = this.params.secondaryLabel ? '' : 'none';
+    const label = this.params.secondaryLabel;
+
+    this.nodes.secondaryLabelEl.innerHTML = label ? makeShortcutHtml(label) : '';
+    this.nodes.secondaryLabelEl.style.display = label ? '' : 'none';
   }
 
   /**
@@ -586,7 +599,7 @@ export class PopoverItemDefault extends PopoverItem {
       return;
     }
 
-    this.nodes.secondaryLabelEl.textContent = secondaryLabel ?? '';
+    this.nodes.secondaryLabelEl.innerHTML = secondaryLabel ? makeShortcutHtml(secondaryLabel) : '';
     this.nodes.secondaryLabelEl.style.display = secondaryLabel ? '' : 'none';
   }
 

package/src/components/utils/popover/popover-abstract.ts

@@ -86,6 +86,11 @@ export abstract class PopoverAbstract<Nodes extends PopoverNodes = PopoverNodes>
     if (this.nodes.popoverContainer) {
       this.listeners.on(this.nodes.popoverContainer, 'click', (event: Event) => this.handleClick(event));
     }
+
+    // Set up scroll listener on items container for scroll hazes
+    if (this.nodes.items) {
+      this.listeners.on(this.nodes.items, 'scroll', () => this.updateScrollHazes());
+    }
   }
 
   /**
@@ -136,6 +141,8 @@ export abstract class PopoverAbstract<Nodes extends PopoverNodes = PopoverNodes>
       this.search.focus();
     }
 
+    this.updateScrollHazes();
+
     const { trigger } = this.params;
     const isRootWithTrigger = (this.params.nestingLevel ?? 0) === 0 && trigger !== undefined;
 
@@ -156,6 +163,9 @@ export abstract class PopoverAbstract<Nodes extends PopoverNodes = PopoverNodes>
 
     this.itemsDefault.forEach(item => item.reset());
 
+    this.nodes.scrollHazeTop.style.opacity = '0';
+    this.nodes.scrollHazeBottom.style.opacity = '0';
+
     if (this.search !== undefined) {
       this.search.clear();
     }
@@ -429,6 +439,24 @@ export abstract class PopoverAbstract<Nodes extends PopoverNodes = PopoverNodes>
     }
   }
 
+  /**
+   * Updates scroll haze visibility based on the items container scroll state.
+   * Shows top haze when scrolled down, bottom haze when more content below.
+   */
+  protected updateScrollHazes(): void {
+    const { items, scrollHazeTop, scrollHazeBottom } = this.nodes;
+
+    const hasOverflow = items.scrollHeight > items.clientHeight;
+    const isAtTop = items.scrollTop <= 0;
+    const isAtBottom = items.scrollTop + items.clientHeight >= items.scrollHeight - 1;
+
+    scrollHazeTop.style.opacity = hasOverflow && !isAtTop ? '1' : '0';
+    scrollHazeBottom.style.opacity = hasOverflow && !isAtBottom ? '1' : '0';
+
+    scrollHazeTop.style.top = `${items.offsetTop}px`;
+    scrollHazeBottom.style.top = `${items.offsetTop + items.clientHeight - scrollHazeBottom.offsetHeight}px`;
+  }
+
   /**
    * Checks if popover contains the node
    * @param node - node to check
@@ -485,9 +513,24 @@ export abstract class PopoverAbstract<Nodes extends PopoverNodes = PopoverNodes>
     items.setAttribute(DATA_ATTR.popoverItems, '');
     items.setAttribute('data-blok-testid', 'popover-items');
 
+    // Create scroll haze overlays
+    const scrollHazeTop = document.createElement('div');
+
+    scrollHazeTop.className = css.scrollHaze;
+    scrollHazeTop.style.background = 'linear-gradient(to bottom, var(--blok-popover-bg), transparent)';
+    scrollHazeTop.style.opacity = '0';
+
+    const scrollHazeBottom = document.createElement('div');
+
+    scrollHazeBottom.className = css.scrollHaze;
+    scrollHazeBottom.style.background = 'linear-gradient(to top, var(--blok-popover-bg), transparent)';
+    scrollHazeBottom.style.opacity = '0';
+
     // Assemble DOM structure
     popoverContainer.appendChild(nothingFoundMessage);
     popoverContainer.appendChild(items);
+    popoverContainer.appendChild(scrollHazeTop);
+    popoverContainer.appendChild(scrollHazeBottom);
     popover.appendChild(popoverContainer);
 
     return {
@@ -495,6 +538,8 @@ export abstract class PopoverAbstract<Nodes extends PopoverNodes = PopoverNodes>
       popoverContainer,
       nothingFoundMessage,
       items,
+      scrollHazeTop,
+      scrollHazeBottom,
     };
   }
 

package/src/components/utils/popover/popover-desktop.ts

@@ -1077,6 +1077,7 @@ export class PopoverDesktop extends PopoverAbstract {
     }
 
     this.toggleNothingFoundMessage(isNothingFound);
+    this.updateScrollHazes();
 
     // Recalculate position since popover height may have changed (trigger-based popovers only;
     // non-trigger popovers use CSS variable positioning that doesn't need pixel recalculation)

package/src/components/utils/popover/popover-position.ts

@@ -32,7 +32,9 @@ export interface ResolvedPosition {
 
 /**
  * Determines whether the popover should flip to the alternate side.
- * Returns true when the popover doesn't fit on the preferred side and the alternate side has more (or equal) space.
+ * Returns true only when the popover fits on the alternate side but not the preferred side.
+ * When neither side fits, stays on the preferred side so the popover remains adjacent
+ * to the anchor instead of getting clamped to a distant boundary edge.
  */
 function shouldFlip(popoverDimension: number, spaceOnPreferred: number, spaceOnAlternate: number): boolean {
   if (popoverDimension <= spaceOnPreferred) {
@@ -43,7 +45,7 @@ function shouldFlip(popoverDimension: number, spaceOnPreferred: number, spaceOnA
     return true;
   }
 
-  return spaceOnAlternate > spaceOnPreferred;
+  return false;
 }
 
 /**
@@ -75,9 +77,14 @@ export function resolvePosition(input: PositionInput): ResolvedPosition {
     ? anchor.top - offset - popoverSize.height + scrollOffset.y
     : anchor.bottom + offset + scrollOffset.y;
 
-  // Clamp: ensure popover doesn't overflow above top boundary
-  const top = rawTop < boundaryTop + scrollOffset.y
-    ? boundaryTop + scrollOffset.y
+  // Clamp: ensure popover doesn't overflow above top boundary.
+  // Use the scope's top in document coords (scopeBounds.top + scrollOffset.y) rather
+  // than the viewport-clamped boundaryTop, so the clamp is correct when the page is
+  // scrolled (boundaryTop is viewport-relative; adding scrollOffset converts it to
+  // document coords but discards any negative scope top that was clamped to 0).
+  const scopeTopInDocCoords = scopeBounds.top + scrollOffset.y;
+  const top = rawTop < scopeTopInDocCoords
+    ? scopeTopInDocCoords
     : rawTop;
 
   // --- Horizontal ---

package/src/components/utils/popover/popover.const.ts

@@ -18,6 +18,8 @@ export const css = {
   popoverOverlay: 'hidden bg-dark',
 
   items: 'overflow-y-auto overscroll-contain',
+
+  scrollHaze: 'absolute inset-x-0 h-6 pointer-events-none z-1 transition-opacity duration-300 ease-in-out',
 };
 
 /**

package/src/components/utils.ts

@@ -73,6 +73,7 @@ export {
 export {
   generateBlockId,
   generateId,
+  isValidBlockId,
 } from './utils/id-generator';
 
 // HTML utilities