angular-grab 0.1.0 → 0.1.2

package/packages/angular-grab/src/core/keyboard/keyboard-handler.ts

@@ -0,0 +1,163 @@
+export interface ParsedKey {
+  key: string;
+  meta: boolean;
+  ctrl: boolean;
+  shift: boolean;
+  alt: boolean;
+}
+
+export interface KeyboardHandler {
+  start(): void;
+  stop(): void;
+  dispose(): void;
+}
+
+export interface KeyboardHandlerDeps {
+  getActivationKey: () => string;
+  getActivationMode: () => 'hold' | 'toggle';
+  getKeyHoldDuration: () => number;
+  getEnableInInputs: () => boolean;
+  onActivate: () => void;
+  onDeactivate: () => void;
+  isActive: () => boolean;
+}
+
+export function isMac(): boolean {
+  if (typeof navigator === 'undefined') return false;
+  const uaData = (navigator as any).userAgentData;
+  if (uaData?.platform) return /mac/i.test(uaData.platform);
+  return /Mac|iPhone|iPad|iPod/i.test(navigator.userAgent);
+}
+
+export function parseKeyCombo(combo: string): ParsedKey {
+  const parts = combo.split('+').map((s) => s.trim());
+  const result: ParsedKey = {
+    key: '',
+    meta: false,
+    ctrl: false,
+    shift: false,
+    alt: false,
+  };
+
+  for (const part of parts) {
+    const lower = part.toLowerCase();
+    if (lower === 'meta' || lower === 'cmd' || lower === 'command') {
+      result.meta = true;
+    } else if (lower === 'ctrl' || lower === 'control') {
+      result.ctrl = true;
+    } else if (lower === 'shift') {
+      result.shift = true;
+    } else if (lower === 'alt' || lower === 'option') {
+      result.alt = true;
+    } else {
+      result.key = lower;
+    }
+  }
+
+  return result;
+}
+
+function matchesCombo(e: KeyboardEvent, parsed: ParsedKey): boolean {
+  if (parsed.meta && !e.metaKey) return false;
+  if (parsed.ctrl && !e.ctrlKey) return false;
+  if (parsed.shift && !e.shiftKey) return false;
+  if (parsed.alt && !e.altKey) return false;
+
+  return e.key.toLowerCase() === parsed.key;
+}
+
+function isInputElement(el: EventTarget | null): boolean {
+  if (!el || !(el instanceof HTMLElement)) return false;
+  const tag = el.tagName;
+  return tag === 'INPUT' || tag === 'TEXTAREA' || el.isContentEditable;
+}
+
+export function createKeyboardHandler(deps: KeyboardHandlerDeps): KeyboardHandler {
+  let holdTimer: ReturnType<typeof setTimeout> | null = null;
+  let holdActivated = false;
+  let listening = false;
+
+  function handleKeyDown(e: KeyboardEvent): void {
+    if (!deps.getEnableInInputs() && isInputElement(e.target)) return;
+
+    const parsed = parseKeyCombo(deps.getActivationKey());
+    if (!matchesCombo(e, parsed)) return;
+
+    const mode = deps.getActivationMode();
+    const holdDuration = deps.getKeyHoldDuration();
+
+    if (mode === 'hold') {
+      e.preventDefault();
+
+      if (holdActivated) return;
+
+      if (holdDuration > 0) {
+        if (holdTimer) return;
+        holdTimer = setTimeout(() => {
+          holdActivated = true;
+          deps.onActivate();
+        }, holdDuration);
+      } else {
+        holdActivated = true;
+        deps.onActivate();
+      }
+    } else {
+      // toggle mode
+      e.preventDefault();
+    }
+  }
+
+  function handleKeyUp(e: KeyboardEvent): void {
+    const parsed = parseKeyCombo(deps.getActivationKey());
+
+    // For key-up we check if the released key matches the main key
+    if (e.key.toLowerCase() !== parsed.key) return;
+
+    const mode = deps.getActivationMode();
+
+    if (mode === 'hold') {
+      if (holdTimer) {
+        clearTimeout(holdTimer);
+        holdTimer = null;
+      }
+      if (holdActivated) {
+        holdActivated = false;
+        deps.onDeactivate();
+      }
+    } else {
+      // toggle mode: toggle on key-up so we don't double-fire
+      if (deps.isActive()) {
+        deps.onDeactivate();
+      } else {
+        deps.onActivate();
+      }
+    }
+  }
+
+  return {
+    start(): void {
+      if (listening) return;
+      listening = true;
+      document.addEventListener('keydown', handleKeyDown, true);
+      document.addEventListener('keyup', handleKeyUp, true);
+    },
+
+    stop(): void {
+      if (!listening) return;
+      listening = false;
+
+      if (holdTimer) {
+        clearTimeout(holdTimer);
+        holdTimer = null;
+      }
+      holdActivated = false;
+
+      document.removeEventListener('keydown', handleKeyDown, true);
+      document.removeEventListener('keyup', handleKeyUp, true);
+    },
+
+    dispose(): void {
+      this.stop();
+    },
+  };
+}

package/packages/angular-grab/src/core/overlay/crosshair.ts

@@ -0,0 +1,107 @@
+import { Z_INDEX_CROSSHAIR } from '../constants';
+
+const CROSSHAIR_STYLE_ID = '__ag-crosshair-styles__';
+const H_LINE_ID = '__ag-crosshair-h__';
+const V_LINE_ID = '__ag-crosshair-v__';
+
+export interface Crosshair {
+  activate(): void;
+  deactivate(): void;
+  isCrosshairElement(el: Element): boolean;
+  dispose(): void;
+}
+
+export function createCrosshair(): Crosshair {
+  let hLine: HTMLDivElement | null = null;
+  let vLine: HTMLDivElement | null = null;
+  let listening = false;
+
+  function injectStyles(): void {
+    if (document.getElementById(CROSSHAIR_STYLE_ID)) return;
+
+    const style = document.createElement('style');
+    style.id = CROSSHAIR_STYLE_ID;
+    style.textContent = `
+      .ag-crosshair-line {
+        position: fixed;
+        pointer-events: none;
+        z-index: ${Z_INDEX_CROSSHAIR};
+        background: var(--ag-accent, #3b82f6);
+        opacity: 0.25;
+        transition: none;
+      }
+      #${H_LINE_ID} {
+        left: 0;
+        right: 0;
+        height: 1px;
+      }
+      #${V_LINE_ID} {
+        top: 0;
+        bottom: 0;
+        width: 1px;
+      }
+      body.ag-crosshair-active {
+        cursor: crosshair !important;
+      }
+    `;
+    document.head.appendChild(style);
+  }
+
+  function ensureElements(): void {
+    if (!hLine) {
+      injectStyles();
+      hLine = document.createElement('div');
+      hLine.id = H_LINE_ID;
+      hLine.className = 'ag-crosshair-line';
+      document.body.appendChild(hLine);
+    }
+    if (!vLine) {
+      vLine = document.createElement('div');
+      vLine.id = V_LINE_ID;
+      vLine.className = 'ag-crosshair-line';
+      document.body.appendChild(vLine);
+    }
+  }
+
+  function handleMouseMove(e: MouseEvent): void {
+    if (hLine) {
+      hLine.style.top = `${e.clientY}px`;
+    }
+    if (vLine) {
+      vLine.style.left = `${e.clientX}px`;
+    }
+  }
+
+  return {
+    activate(): void {
+      if (listening) return;
+      listening = true;
+      ensureElements();
+      document.body.classList.add('ag-crosshair-active');
+      document.addEventListener('mousemove', handleMouseMove, true);
+    },
+
+    deactivate(): void {
+      if (!listening) return;
+      listening = false;
+      document.body.classList.remove('ag-crosshair-active');
+      document.removeEventListener('mousemove', handleMouseMove, true);
+      if (hLine) hLine.style.top = '-10px';
+      if (vLine) vLine.style.left = '-10px';
+    },
+
+    isCrosshairElement(el: Element): boolean {
+      return el === hLine || el === vLine
+        || el.id === H_LINE_ID || el.id === V_LINE_ID;
+    },
+
+    dispose(): void {
+      this.deactivate();
+      hLine?.remove();
+      vLine?.remove();
+      document.getElementById(CROSSHAIR_STYLE_ID)?.remove();
+      hLine = null;
+      vLine = null;
+    },
+  };
+}

package/packages/angular-grab/src/core/overlay/freeze-overlay.ts

@@ -0,0 +1,239 @@
+import { Z_INDEX_FREEZE } from '../constants';
+
+const FREEZE_ID = '__ag-freeze-overlay__';
+const FREEZE_STYLE_ID = '__ag-freeze-styles__';
+const HOVER_STYLE_ID = '__ag-freeze-hover-styles__';
+const ANIM_STYLE_ID = '__ag-freeze-anim-styles__';
+const HOVER_ATTR = 'data-ag-hover';
+
+/**
+ * Events to block during freeze to prevent hover state changes.
+ * Adapted from react-grab's freeze-pseudo-states.ts
+ */
+const MOUSE_EVENTS_TO_BLOCK = [
+  'mouseenter', 'mouseleave', 'mouseover', 'mouseout',
+  'pointerenter', 'pointerleave', 'pointerover', 'pointerout',
+] as const;
+
+const FOCUS_EVENTS_TO_BLOCK = ['focus', 'blur', 'focusin', 'focusout'] as const;
+
+export interface FreezeOverlay {
+  show(hoveredElement?: Element | null): void;
+  hide(): void;
+  isVisible(): boolean;
+  isFreezeElement(el: Element): boolean;
+  getElement(): HTMLDivElement | null;
+  dispose(): void;
+}
+
+export function createFreezeOverlay(): FreezeOverlay {
+  let overlay: HTMLDivElement | null = null;
+  let visible = false;
+  let hoverStyleEl: HTMLStyleElement | null = null;
+  let animStyleEl: HTMLStyleElement | null = null;
+  let markedElements: Element[] = [];
+
+  function injectStyles(): void {
+    if (document.getElementById(FREEZE_STYLE_ID)) return;
+
+    const style = document.createElement('style');
+    style.id = FREEZE_STYLE_ID;
+    style.textContent = `
+      #${FREEZE_ID} {
+        position: fixed;
+        top: 0;
+        left: 0;
+        width: 100vw;
+        height: 100vh;
+        z-index: ${Z_INDEX_FREEZE};
+        pointer-events: auto;
+        background: transparent;
+      }
+    `;
+    document.head.appendChild(style);
+  }
+
+  function ensureOverlay(): HTMLDivElement {
+    if (overlay) return overlay;
+
+    injectStyles();
+    overlay = document.createElement('div');
+    overlay.id = FREEZE_ID;
+    overlay.style.display = 'none';
+    document.body.appendChild(overlay);
+    return overlay;
+  }
+
+  // --- Event blocking (from react-grab's freeze-pseudo-states.ts) ---
+
+  const stopEvent = (e: Event): void => {
+    e.stopImmediatePropagation();
+  };
+
+  const preventFocusChange = (e: Event): void => {
+    e.preventDefault();
+    e.stopImmediatePropagation();
+  };
+
+  function blockEvents(): void {
+    for (const type of MOUSE_EVENTS_TO_BLOCK) {
+      document.addEventListener(type, stopEvent, true);
+    }
+    for (const type of FOCUS_EVENTS_TO_BLOCK) {
+      document.addEventListener(type, preventFocusChange, true);
+    }
+  }
+
+  function unblockEvents(): void {
+    for (const type of MOUSE_EVENTS_TO_BLOCK) {
+      document.removeEventListener(type, stopEvent, true);
+    }
+    for (const type of FOCUS_EVENTS_TO_BLOCK) {
+      document.removeEventListener(type, preventFocusChange, true);
+    }
+  }
+
+  // --- Hover preservation via CSS rule cloning ---
+
+  /** Mark the hovered element and all ancestors with [data-ag-hover]. */
+  function markHoverChain(element: Element): void {
+    let current: Element | null = element;
+    while (current && current !== document.documentElement) {
+      current.setAttribute(HOVER_ATTR, '');
+      markedElements.push(current);
+      current = current.parentElement;
+    }
+  }
+
+  function clearHoverMarks(): void {
+    for (const el of markedElements) {
+      el.removeAttribute(HOVER_ATTR);
+    }
+    markedElements = [];
+  }
+
+  /**
+   * Walk all stylesheets and clone :hover rules as [data-ag-hover] rules.
+   * This preserves hover-dependent visibility of child elements
+   * (e.g. `.trigger:hover .tooltip { display: block }`) which
+   * computed-style snapshotting alone cannot handle.
+   */
+  function injectHoverRules(): void {
+    if (hoverStyleEl) return;
+
+    const cloned: string[] = [];
+
+    for (const sheet of Array.from(document.styleSheets)) {
+      let rules: CSSRuleList;
+      try {
+        rules = sheet.cssRules;
+      } catch {
+        continue; // cross-origin stylesheet
+      }
+      collectHoverRules(rules, cloned);
+    }
+
+    if (cloned.length === 0) return;
+
+    hoverStyleEl = document.createElement('style');
+    hoverStyleEl.id = HOVER_STYLE_ID;
+    hoverStyleEl.textContent = cloned.join('\n');
+    document.head.appendChild(hoverStyleEl);
+  }
+
+  function collectHoverRules(rules: CSSRuleList, out: string[]): void {
+    for (const rule of Array.from(rules)) {
+      if (rule instanceof CSSStyleRule) {
+        if (rule.selectorText.includes(':hover')) {
+          const newSelector = rule.selectorText.replace(/:hover/g, `[${HOVER_ATTR}]`);
+          out.push(`${newSelector} { ${rule.style.cssText} }`);
+        }
+      } else if (rule instanceof CSSMediaRule) {
+        const inner: string[] = [];
+        collectHoverRules(rule.cssRules, inner);
+        if (inner.length > 0) {
+          out.push(`@media ${rule.conditionText} { ${inner.join('\n')} }`);
+        }
+      }
+    }
+  }
+
+  function removeHoverRules(): void {
+    hoverStyleEl?.remove();
+    hoverStyleEl = null;
+  }
+
+  // --- Animation freezing (from react-grab's freeze-animations.ts) ---
+
+  function freezeAnimations(): void {
+    if (animStyleEl) return;
+
+    animStyleEl = document.createElement('style');
+    animStyleEl.id = ANIM_STYLE_ID;
+    animStyleEl.textContent = `
+      *, *::before, *::after {
+        animation-play-state: paused !important;
+        transition: none !important;
+      }
+    `;
+    document.head.appendChild(animStyleEl);
+  }
+
+  function unfreezeAnimations(): void {
+    animStyleEl?.remove();
+    animStyleEl = null;
+  }
+
+  return {
+    show(hoveredElement?: Element | null): void {
+      // 1. Block mouse/focus events to prevent hover state changes
+      blockEvents();
+
+      // 2. Preserve hover state via CSS rule cloning BEFORE overlay steals hover
+      if (hoveredElement) {
+        markHoverChain(hoveredElement);
+        injectHoverRules();
+      }
+
+      // 3. Freeze animations so nothing moves while page is frozen
+      freezeAnimations();
+
+      // 4. Show overlay to block clicks/scrolls
+      const el = ensureOverlay();
+      el.style.display = 'block';
+      visible = true;
+    },
+
+    hide(): void {
+      if (overlay) overlay.style.display = 'none';
+      visible = false;
+      clearHoverMarks();
+      removeHoverRules();
+      unfreezeAnimations();
+      unblockEvents();
+    },
+
+    isVisible(): boolean {
+      return visible;
+    },
+
+    isFreezeElement(el: Element): boolean {
+      return el === overlay || el.id === FREEZE_ID;
+    },
+
+    getElement(): HTMLDivElement | null {
+      return overlay;
+    },
+
+    dispose(): void {
+      clearHoverMarks();
+      removeHoverRules();
+      unfreezeAnimations();
+      unblockEvents();
+      overlay?.remove();
+      document.getElementById(FREEZE_STYLE_ID)?.remove();
+      overlay = null;
+      visible = false;
+    },
+  };
+}

package/packages/angular-grab/src/core/overlay/overlay-renderer.ts

@@ -0,0 +1,180 @@
+import { Z_INDEX_OVERLAY, Z_INDEX_LABEL } from '../constants';
+
+const OVERLAY_ID = '__ag-overlay__';
+const LABEL_ID = '__ag-label__';
+const STYLE_ID = '__ag-styles__';
+
+export interface OverlayRenderer {
+  show(element: Element, componentName: string | null, sourcePath?: string | null, cssClasses?: string[]): void;
+  hide(): void;
+  isOverlayElement(el: Element): boolean;
+  dispose(): void;
+}
+
+export function createOverlayRenderer(): OverlayRenderer {
+  let overlay: HTMLDivElement | null = null;
+  let label: HTMLDivElement | null = null;
+  let rafId: number | null = null;
+  let currentElement: Element | null = null;
+  let currentComponentName: string | null = null;
+  let currentSourcePath: string | null = null;
+  let currentCssClasses: string[] = [];
+
+  function injectStyles(): void {
+    if (document.getElementById(STYLE_ID)) return;
+
+    const style = document.createElement('style');
+    style.id = STYLE_ID;
+    style.textContent = `
+      #${OVERLAY_ID} {
+        position: fixed;
+        pointer-events: none;
+        z-index: ${Z_INDEX_OVERLAY};
+        border: 2px solid var(--ag-overlay-border, #3b82f6);
+        background: var(--ag-overlay-bg, rgba(59, 130, 246, 0.1));
+        transition: top 0.05s ease, left 0.05s ease, width 0.05s ease, height 0.05s ease;
+        box-sizing: border-box;
+      }
+      #${LABEL_ID} {
+        position: fixed;
+        pointer-events: none;
+        z-index: ${Z_INDEX_LABEL};
+        background: var(--ag-label-bg, #3b82f6);
+        color: var(--ag-label-text, #fff);
+        font: 11px/1.4 monospace;
+        padding: 2px 6px;
+        border-radius: 3px;
+        white-space: nowrap;
+        box-sizing: border-box;
+        max-width: 100vw;
+        overflow: hidden;
+        text-overflow: ellipsis;
+      }
+    `;
+    document.head.appendChild(style);
+  }
+
+  function ensureElements(): void {
+    if (!overlay) {
+      injectStyles();
+      overlay = document.createElement('div');
+      overlay.id = OVERLAY_ID;
+      document.body.appendChild(overlay);
+    }
+    if (!label) {
+      label = document.createElement('div');
+      label.id = LABEL_ID;
+      document.body.appendChild(label);
+    }
+  }
+
+  function positionOverlay(): void {
+    if (!currentElement || !overlay || !label) return;
+
+    const rect = currentElement.getBoundingClientRect();
+
+    // Hide overlay if element is detached or has zero dimensions
+    if (rect.width === 0 && rect.height === 0 && !currentElement.isConnected) {
+      overlay.style.display = 'none';
+      label.style.display = 'none';
+      return;
+    }
+
+    overlay.style.top = `${rect.top}px`;
+    overlay.style.left = `${rect.left}px`;
+    overlay.style.width = `${rect.width}px`;
+    overlay.style.height = `${rect.height}px`;
+    overlay.style.display = 'block';
+
+    const tag = currentElement.tagName.toLowerCase();
+    let labelText = `<${tag}>`;
+    if (currentCssClasses.length > 0) {
+      labelText += ` .${currentCssClasses.join('.')}`;
+    }
+    if (currentComponentName) {
+      labelText += ` in ${currentComponentName}`;
+    }
+    if (currentSourcePath) {
+      labelText += ` \u2014 ${currentSourcePath}`;
+    }
+    label.textContent = labelText;
+
+    // Position label above the element, or below if no room
+    const labelHeight = 20;
+    const gap = 4;
+    let labelTop = rect.top - labelHeight - gap;
+    if (labelTop < 0) {
+      labelTop = rect.bottom + gap;
+    }
+
+    // Clamp label horizontally to viewport
+    let labelLeft = rect.left;
+    label.style.top = `${labelTop}px`;
+    label.style.left = `${labelLeft}px`;
+    label.style.display = 'block';
+
+    // After rendering, check if it overflows right edge
+    const labelRect = label.getBoundingClientRect();
+    const viewportWidth = document.documentElement.clientWidth;
+    if (labelRect.right > viewportWidth) {
+      labelLeft = Math.max(0, viewportWidth - labelRect.width);
+      label.style.left = `${labelLeft}px`;
+    }
+    if (labelLeft < 0) {
+      label.style.left = '0px';
+    }
+  }
+
+  function trackPosition(): void {
+    positionOverlay();
+    rafId = requestAnimationFrame(trackPosition);
+  }
+
+  function stopTracking(): void {
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId);
+      rafId = null;
+    }
+  }
+
+  return {
+    show(element: Element, componentName: string | null, sourcePath?: string | null, cssClasses?: string[]): void {
+      ensureElements();
+      currentElement = element;
+      currentComponentName = componentName;
+      currentSourcePath = sourcePath ?? null;
+      currentCssClasses = cssClasses ?? [];
+      stopTracking();
+      trackPosition();
+    },
+
+    hide(): void {
+      stopTracking();
+      currentElement = null;
+      currentComponentName = null;
+      currentSourcePath = null;
+      currentCssClasses = [];
+
+      if (overlay) overlay.style.display = 'none';
+      if (label) label.style.display = 'none';
+    },
+
+    isOverlayElement(el: Element): boolean {
+      return el === overlay || el === label || el.id === OVERLAY_ID || el.id === LABEL_ID;
+    },
+
+    dispose(): void {
+      stopTracking();
+      currentElement = null;
+      currentComponentName = null;
+      currentSourcePath = null;
+      currentCssClasses = [];
+
+      overlay?.remove();
+      label?.remove();
+      document.getElementById(STYLE_ID)?.remove();
+      overlay = null;
+      label = null;
+    },
+  };
+}