@jackuait/blok 0.10.3 → 0.10.5

package/src/components/modules/uiControllers/controllers/selection.ts

@@ -167,10 +167,22 @@ export class SelectionController extends Controller {
    * @returns true if current block should be updated
    */
   private shouldUpdateCurrentBlock(): boolean {
+    const focusedElement = Selection.anchorElement;
+
+    if (!focusedElement || !this.wrapperElement) {
+      return false;
+    }
+
     /**
-     * Always update current block when focus moves to a different block.
-     * This handles Tab key navigation, programmatic focus, and accessibility tools.
+     * Skip updating current block when focus is inside a nested editor instance.
+     * The closest editor wrapper must match this instance's wrapper.
      */
+    const closestEditor = focusedElement.closest('[data-blok-testid="blok-editor"]');
+
+    if (closestEditor !== null && closestEditor !== this.wrapperElement) {
+      return false;
+    }
+
     return true;
   }
 }

package/src/components/modules/yjs/document-store.ts

@@ -193,6 +193,28 @@ export class DocumentStore {
     }, 'local');
   }
 
+  /**
+   * Update a block's edit metadata fields directly on the Y.Map.
+   * @param id - Block id
+   * @param lastEditedAt - Timestamp in milliseconds
+   * @param lastEditedBy - User display name, or null
+   */
+  public updateBlockMetadata(id: string, lastEditedAt: number, lastEditedBy: string | null): void {
+    const yblock = this.getBlockById(id);
+
+    if (yblock === undefined) {
+      return;
+    }
+
+    this.transact(() => {
+      yblock.set('lastEditedAt', lastEditedAt);
+
+      if (lastEditedBy !== null) {
+        yblock.set('lastEditedBy', lastEditedBy);
+      }
+    }, 'local');
+  }
+
   /**
    * Find block index by id.
    * @param id - Block id to find

package/src/components/modules/yjs/index.ts

@@ -164,6 +164,16 @@ export class YjsManager extends Module {
     this.documentStore.updateBlockTune(id, tuneName, tuneData);
   }
 
+  /**
+   * Update a block's edit metadata.
+   * @param id - Block id
+   * @param lastEditedAt - Timestamp in milliseconds
+   * @param lastEditedBy - User display name, or null
+   */
+  public updateBlockMetadata(id: string, lastEditedAt: number, lastEditedBy: string | null): void {
+    this.documentStore.updateBlockMetadata(id, lastEditedAt, lastEditedBy);
+  }
+
   /**
    * Get block Y.Map by id.
    * @param id - Block id

package/src/components/modules/yjs/serializer.ts

@@ -74,6 +74,14 @@ export class YBlockSerializer {
       yblock.set('contentIds', Y.Array.from(blockData.content));
     }
 
+    if (blockData.lastEditedAt !== undefined) {
+      yblock.set('lastEditedAt', blockData.lastEditedAt);
+    }
+
+    if (blockData.lastEditedBy !== undefined) {
+      yblock.set('lastEditedBy', blockData.lastEditedBy);
+    }
+
     return yblock;
   }
 
@@ -122,6 +130,18 @@ export class YBlockSerializer {
       block.content = contentIds.toArray();
     }
 
+    const lastEditedAt = yblock.get('lastEditedAt');
+
+    if (typeof lastEditedAt === 'number') {
+      block.lastEditedAt = lastEditedAt;
+    }
+
+    const lastEditedBy = yblock.get('lastEditedBy');
+
+    if (typeof lastEditedBy === 'string') {
+      block.lastEditedBy = lastEditedBy;
+    }
+
     return block;
   }
 

package/src/components/ui/toolbox.ts

@@ -427,7 +427,6 @@ export class Toolbox extends EventsDispatcher<ToolboxEventMap> {
     const PopoverClass = isMobileScreen() ? PopoverMobile : PopoverDesktop;
 
     this.popover = new PopoverClass({
-      scopeElement: this.api.ui.nodes.redactor,
       trigger: this.triggerElement || this.nodes.toolbox,
       leftAlignElement: this.leftAlignElement,
       messages: {

package/src/components/utils/id-generator.ts

@@ -20,6 +20,17 @@ export const generateBlockId = (): string => {
   return nanoid(idLen);
 };
 
+/**
+ * Nanoid-compatible block ID pattern: exactly 10 URL-safe characters (A-Z, a-z, 0-9, _, -)
+ */
+const BLOCK_ID_PATTERN = /^[A-Za-z0-9_-]{10}$/;
+
+/**
+ * Returns true if the given string is a valid block ID (nanoid format).
+ * @param id - string to check
+ */
+export const isValidBlockId = (id: string): boolean => BLOCK_ID_PATTERN.test(id);
+
 /**
  * Returns random generated identifier
  * @param prefix - identifier prefix

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;
 }
 
 /**

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