@blorkfield/blork-tabs 0.3.0 → 0.4.0

package/src/AutoHideManager.ts

@@ -19,6 +19,7 @@ export class AutoHideManager {
   private classes: CSSClasses;
   private callbacks: AutoHideCallbacks;
   private hideTimers: Map<string, ReturnType<typeof setTimeout>> = new Map();
+  private pausedPanels: Set<string> = new Set();
   private boundActivityHandler: () => void;
   private listenersAttached = false;
 
@@ -49,6 +50,10 @@ export class AutoHideManager {
    */
   private handleActivity(): void {
     for (const panel of this.panels.values()) {
+      // Pinned panels are immune to activity-based show/hide
+      if (panel.isPinned) continue;
+      // Skip paused panels - they handle their own timing
+      if (this.pausedPanels.has(panel.id)) continue;
       // Only process panels that participate in auto-hide
       if (panel.resolvedAutoHideDelay !== undefined || panel.isHidden) {
         this.show(panel, 'activity');
@@ -62,7 +67,7 @@ export class AutoHideManager {
   /**
    * Schedule a panel to hide after its delay
    */
-  private scheduleHide(panel: PanelState): void {
+  scheduleHide(panel: PanelState): void {
     this.clearTimer(panel.id);
     if (panel.resolvedAutoHideDelay === undefined) return;
 
@@ -75,7 +80,7 @@ export class AutoHideManager {
   /**
    * Clear hide timer for a panel
    */
-  private clearTimer(panelId: string): void {
+  clearTimer(panelId: string): void {
     const timer = this.hideTimers.get(panelId);
     if (timer) {
       clearTimeout(timer);
@@ -83,6 +88,25 @@ export class AutoHideManager {
     }
   }
 
+  /**
+   * Pause auto-hide timer for a panel (e.g., during debug hover)
+   */
+  pauseTimer(panelId: string): void {
+    this.clearTimer(panelId);
+    this.pausedPanels.add(panelId);
+  }
+
+  /**
+   * Resume auto-hide timer for a panel
+   */
+  resumeTimer(panelId: string): void {
+    this.pausedPanels.delete(panelId);
+    const panel = this.panels.get(panelId);
+    if (panel && panel.resolvedAutoHideDelay !== undefined) {
+      this.scheduleHide(panel);
+    }
+  }
+
   /**
    * Show a panel
    */
@@ -97,10 +121,29 @@ export class AutoHideManager {
    */
   hide(panel: PanelState, trigger: 'timeout' | 'api'): void {
     if (panel.isHidden) return;
+    if (panel.isPinned) return; // Pinned panels are always visible
     hidePanel(panel, this.classes);
     this.callbacks.onHide?.(panel, trigger);
   }
 
+  /**
+   * Called when a panel's pin state changes.
+   * Pinning cancels the hide timer and reveals the panel if hidden.
+   * Unpinning restarts the timer if the panel participates in auto-hide.
+   */
+  onPanelPinChanged(panel: PanelState): void {
+    if (panel.isPinned) {
+      this.clearTimer(panel.id);
+      if (panel.isHidden) {
+        this.show(panel, 'api');
+      }
+    } else {
+      if (!panel.isHidden && panel.resolvedAutoHideDelay !== undefined) {
+        this.scheduleHide(panel);
+      }
+    }
+  }
+
   /**
    * Initialize a newly added panel's auto-hide state
    */

package/src/DebugPanel.ts

@@ -3,7 +3,7 @@
  * In-browser debug log panel for environments without console access
  */
 
-import type { DebugPanelConfig, DebugPanel, DebugLogLevel, PanelState, CSSClasses } from './types';
+import type { DebugPanelConfig, DebugPanel, DebugLog, DebugLogConfig, DebugLogLevel, PanelState, CSSClasses } from './types';
 
 export interface DebugPanelElements {
   logContainer: HTMLDivElement;
@@ -30,7 +30,8 @@ export function createDebugPanelContent(
 }
 
 /**
- * Create the interface for interacting with a debug panel
+ * Create the interface for interacting with a debug panel.
+ * Uses the shared createDebugLogInterface internally.
  */
 export function createDebugPanelInterface(
   panel: PanelState,
@@ -38,12 +39,46 @@ export function createDebugPanelInterface(
   config: DebugPanelConfig,
   classes: CSSClasses
 ): DebugPanel {
+  const debugLog = createDebugLogInterface(elements.logContainer, config, classes);
+  return {
+    panel,
+    ...debugLog,
+  };
+}
+
+/**
+ * Escape HTML special characters to prevent XSS
+ */
+function escapeHtml(str: string): string {
+  const div = document.createElement('div');
+  div.textContent = str;
+  return div.innerHTML;
+}
+
+/**
+ * Shared interface config for debug log creation
+ */
+interface DebugLogInterfaceConfig {
+  maxEntries?: number;
+  showTimestamps?: boolean;
+}
+
+/**
+ * Create the logging interface for a debug log container.
+ * This is the shared implementation used by both standalone panels and embedded logs.
+ */
+export function createDebugLogInterface(
+  logContainer: HTMLElement,
+  config: DebugLogInterfaceConfig,
+  classes: CSSClasses
+): DebugLog {
   const maxEntries = config.maxEntries ?? 50;
   const showTimestamps = config.showTimestamps ?? false;
+  const entryClass = classes.debugLogEntry;
 
   function addEntry(level: DebugLogLevel, eventName: string, data?: Record<string, unknown>): void {
     const entry = document.createElement('div');
-    entry.className = classes.debugLogEntry;
+    entry.className = entryClass;
 
     // Add level-specific class for color coding
     if (level === 'warn') entry.classList.add(classes.debugLogEntryWarn);
@@ -69,30 +104,165 @@ export function createDebugPanelInterface(
     }
 
     entry.innerHTML = html;
-    elements.logContainer.appendChild(entry);
-    elements.logContainer.scrollTop = elements.logContainer.scrollHeight;
+    logContainer.appendChild(entry);
+    logContainer.scrollTop = logContainer.scrollHeight;
 
-    // Remove oldest entries if over limit
-    while (elements.logContainer.children.length > maxEntries) {
-      elements.logContainer.removeChild(elements.logContainer.children[0]);
+    // Remove oldest entries if over limit (only count actual log entries, not the close button)
+    const entries = logContainer.querySelectorAll(`.${entryClass}`);
+    if (entries.length > maxEntries) {
+      const toRemove = entries.length - maxEntries;
+      for (let i = 0; i < toRemove; i++) {
+        entries[i].remove();
+      }
     }
   }
 
+  function clearEntries(): void {
+    // Only remove log entries, preserve the close button
+    const entries = logContainer.querySelectorAll(`.${entryClass}`);
+    entries.forEach(entry => entry.remove());
+  }
+
   return {
-    panel,
     log: (name, data) => addEntry('log', name, data),
     info: (name, data) => addEntry('info', name, data),
     warn: (name, data) => addEntry('warn', name, data),
     error: (name, data) => addEntry('error', name, data),
-    clear: () => { elements.logContainer.innerHTML = ''; }
+    clear: clearEntries,
   };
 }
 
+export interface DebugLogSetup {
+  debugLog: DebugLog;
+  logContainer: HTMLDivElement;
+}
+
 /**
- * Escape HTML special characters to prevent XSS
+ * Create an embeddable debug log in any container element
  */
-function escapeHtml(str: string): string {
-  const div = document.createElement('div');
-  div.textContent = str;
-  return div.innerHTML;
+export function createDebugLog(
+  container: HTMLElement,
+  config: DebugLogConfig,
+  classes: CSSClasses
+): DebugLogSetup {
+  // Create log container
+  const logContainer = document.createElement('div');
+  logContainer.className = classes.debugLog;
+  container.appendChild(logContainer);
+
+  // Use shared interface creation
+  const debugLog = createDebugLogInterface(logContainer, config, classes);
+
+  return { debugLog, logContainer };
+}
+
+export interface HoverEnlargeConfig {
+  /** The log container element (.blork-tabs-debug-log) to enlarge */
+  logContainer: HTMLElement;
+  /** Hover delay in ms (0 = disable) */
+  hoverDelay: number;
+  /** Container to append backdrop to */
+  backdropContainer: HTMLElement;
+  /** CSS classes */
+  classes: CSSClasses;
+  /** Called when hovering starts */
+  onHoverStart?: () => void;
+  /** Called when hovering ends (without enlarging) */
+  onHoverEnd?: () => void;
+  /** Called when enlarged view is closed */
+  onClose?: () => void;
+}
+
+/**
+ * Set up hover-to-enlarge behavior for a debug log container.
+ * Works the same for both standalone debug panels and embedded logs.
+ */
+export function setupHoverEnlarge(config: HoverEnlargeConfig): void {
+  const { logContainer, hoverDelay, backdropContainer, classes, onHoverStart, onHoverEnd, onClose } = config;
+
+  // Add debug panel class for hover border effect
+  logContainer.classList.add(classes.debugPanel);
+
+  // Create close button inside the log container
+  const closeBtn = document.createElement('button');
+  closeBtn.className = classes.debugClearButton;
+  closeBtn.textContent = '×';
+  closeBtn.title = 'Close enlarged view';
+  logContainer.appendChild(closeBtn);
+
+  let hoverTimeout: ReturnType<typeof setTimeout> | null = null;
+  let isEnlarged = false;
+  let backdrop: HTMLDivElement | null = null;
+  let originalParent: HTMLElement | null = null;
+  let placeholder: Comment | null = null;
+
+  const closeEnlarged = () => {
+    if (!isEnlarged) return;
+    isEnlarged = false;
+    logContainer.classList.remove(classes.debugPanelEnlarged);
+
+    // Move log container back to original parent
+    if (originalParent && placeholder) {
+      originalParent.insertBefore(logContainer, placeholder);
+      placeholder.remove();
+      placeholder = null;
+      originalParent = null;
+    }
+
+    if (backdrop) {
+      backdrop.remove();
+      backdrop = null;
+    }
+    onClose?.();
+  };
+
+  const openEnlarged = () => {
+    if (isEnlarged) return;
+    isEnlarged = true;
+
+    // Create backdrop
+    backdrop = document.createElement('div');
+    backdrop.className = classes.debugBackdrop;
+    backdropContainer.appendChild(backdrop);
+
+    // Click backdrop to close
+    backdrop.addEventListener('click', closeEnlarged);
+
+    // Move log container to body to escape parent stacking context
+    originalParent = logContainer.parentElement;
+    placeholder = document.createComment('debug-log-placeholder');
+    originalParent?.insertBefore(placeholder, logContainer);
+    backdropContainer.appendChild(logContainer);
+
+    // Add enlarged class to log container
+    logContainer.classList.add(classes.debugPanelEnlarged);
+  };
+
+  // Hover to start enlarge timer
+  logContainer.addEventListener('mouseenter', () => {
+    onHoverStart?.();
+    if (isEnlarged) return;
+    if (hoverDelay > 0) {
+      hoverTimeout = setTimeout(() => {
+        openEnlarged();
+      }, hoverDelay);
+    }
+  });
+
+  // Cancel timer if mouse leaves
+  logContainer.addEventListener('mouseleave', () => {
+    if (hoverTimeout) {
+      clearTimeout(hoverTimeout);
+      hoverTimeout = null;
+    }
+    if (!isEnlarged) {
+      onHoverEnd?.();
+    }
+  });
+
+  // Close button closes enlarged view
+  closeBtn.addEventListener('click', (e) => {
+    e.stopPropagation();
+    closeEnlarged();
+  });
 }

package/src/DragManager.ts

@@ -13,7 +13,7 @@ import type {
   ResolvedTabManagerConfig,
 } from './types';
 import {
-  getConnectedGroup,
+  getMovingGroupRespectingPins,
   detachFromGroup,
   findSnapTarget,
   snapPanelsToTarget,
@@ -76,24 +76,24 @@ export class DragManager {
     e.preventDefault();
     e.stopPropagation();
 
-    const connectedPanels = getConnectedGroup(panel, this.panels);
-
-    // Store initial positions
-    const initialGroupPositions = new Map<string, Position>();
-    for (const p of connectedPanels) {
-      const rect = p.element.getBoundingClientRect();
-      initialGroupPositions.set(p.id, { x: rect.left, y: rect.top });
-    }
-
     let movingPanels: PanelState[];
 
     if (mode === 'single') {
-      // Detach this panel from its group
+      // Detach this panel from its group and move it alone
       detachFromGroup(panel, this.panels);
       movingPanels = [panel];
     } else {
-      // Move entire group
-      movingPanels = connectedPanels;
+      // Group drag: collect panels on either side of the grabbed panel,
+      // splitting at any pinned panel and severing those bonds
+      movingPanels = getMovingGroupRespectingPins(panel, this.panels);
+      if (movingPanels.length === 0) return;
+    }
+
+    // Store initial positions for the panels that will actually move
+    const initialGroupPositions = new Map<string, Position>();
+    for (const p of movingPanels) {
+      const rect = p.element.getBoundingClientRect();
+      initialGroupPositions.set(p.id, { x: rect.left, y: rect.top });
     }
 
     const rect = panel.element.getBoundingClientRect();

package/src/Panel.ts

@@ -9,6 +9,9 @@ import type {
   CSSClasses,
 } from './types';
 
+const PIN_ICON_UNPINNED = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="display:block"><line x1="12" y1="17" x2="12" y2="22"/><path d="M5 17H19V16L17 11V4H7L5 11V16Z"/><line x1="5" y1="11" x2="19" y2="11"/></svg>`;
+const PIN_ICON_PINNED = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="14" height="14" fill="currentColor" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="display:block;transform:rotate(90deg)"><line x1="12" y1="17" x2="12" y2="22"/><path d="M5 17H19V16L17 11V4H7L5 11V16Z"/><line x1="5" y1="11" x2="19" y2="11"/></svg>`;
+
 /**
  * Creates the default panel DOM structure
  */
@@ -18,6 +21,7 @@ export function createPanelElement(
 ): {
   element: HTMLDivElement;
   dragHandle: HTMLDivElement;
+  pinButton: HTMLButtonElement | null;
   collapseButton: HTMLButtonElement | null;
   contentWrapper: HTMLDivElement;
   detachGrip: HTMLDivElement | null;
@@ -50,6 +54,16 @@ export function createPanelElement(
     header.appendChild(title);
   }
 
+  // Pin button (only if explicitly pinnable)
+  let pinButton: HTMLButtonElement | null = null;
+  if (config.pinnable === true) {
+    pinButton = document.createElement('button');
+    pinButton.className = classes.pinButton;
+    pinButton.id = `${config.id}-pin-btn`;
+    pinButton.innerHTML = config.startPinned === true ? PIN_ICON_PINNED : PIN_ICON_UNPINNED;
+    header.appendChild(pinButton);
+  }
+
   // Collapse button (if collapsible)
   let collapseButton: HTMLButtonElement | null = null;
   if (config.collapsible !== false) {
@@ -84,6 +98,7 @@ export function createPanelElement(
   return {
     element,
     dragHandle: header,
+    pinButton,
     collapseButton,
     contentWrapper,
     detachGrip,
@@ -100,6 +115,7 @@ export function createPanelState(
 ): PanelState {
   let element: HTMLDivElement;
   let dragHandle: HTMLDivElement;
+  let pinButton: HTMLButtonElement | null;
   let collapseButton: HTMLButtonElement | null;
   let contentWrapper: HTMLDivElement;
   let detachGrip: HTMLDivElement | null;
@@ -108,6 +124,7 @@ export function createPanelState(
     // Use existing DOM elements
     element = config.element;
     dragHandle = config.dragHandle ?? (element.querySelector(`.${classes.panelHeader}`) as HTMLDivElement);
+    pinButton = config.pinButton ?? (element.querySelector(`.${classes.pinButton}`) as HTMLButtonElement | null);
     collapseButton = config.collapseButton ?? (element.querySelector(`.${classes.collapseButton}`) as HTMLButtonElement | null);
     contentWrapper = config.contentWrapper ?? (element.querySelector(`.${classes.panelContent}`) as HTMLDivElement);
     detachGrip = config.detachGrip ?? (element.querySelector(`.${classes.detachGrip}`) as HTMLDivElement | null);
@@ -116,6 +133,7 @@ export function createPanelState(
     const created = createPanelElement(config, classes);
     element = created.element;
     dragHandle = created.dragHandle;
+    pinButton = created.pinButton;
     collapseButton = created.collapseButton;
     contentWrapper = created.contentWrapper;
     detachGrip = created.detachGrip;
@@ -136,9 +154,11 @@ export function createPanelState(
     id: config.id,
     element,
     dragHandle,
+    pinButton,
     collapseButton,
     contentWrapper,
     detachGrip,
+    isPinned: config.startPinned === true,
     isCollapsed: config.startCollapsed !== false,
     snappedTo: null,
     snappedFrom: null,
@@ -172,6 +192,23 @@ export function toggleCollapse(
   return newState;
 }
 
+/**
+ * Toggle panel pin state
+ */
+export function togglePin(
+  state: PanelState,
+  pinned?: boolean
+): boolean {
+  const newState = pinned ?? !state.isPinned;
+  state.isPinned = newState;
+
+  if (state.pinButton) {
+    state.pinButton.innerHTML = newState ? PIN_ICON_PINNED : PIN_ICON_UNPINNED;
+  }
+
+  return newState;
+}
+
 /**
  * Show a hidden panel
  */

package/src/SnapChain.ts

@@ -273,6 +273,51 @@ export function snapPanels(
   rightPanel.snappedFrom = leftPanel.id;
 }
 
+/**
+ * Get the subset of connected panels that should move when a panel is grabbed,
+ * stopping at any pinned panel in the chain.
+ *
+ * Pinned panels act as immoveable barriers — the chain splits at each one,
+ * and only the panels on the same side as the grabbed panel are returned.
+ * The snap bonds at each pin boundary are severed as a side effect.
+ *
+ * Example: chain [A, B, P(pinned), C, D], grab B → returns [A, B], unseats B↔P
+ * Example: chain [A, P(pinned), B, C], grab C → returns [B, C], unseats P↔B
+ */
+export function getMovingGroupRespectingPins(
+  grabbedPanel: PanelState,
+  panels: Map<string, PanelState>
+): PanelState[] {
+  if (grabbedPanel.isPinned) return [];
+
+  const fullGroup = getConnectedGroup(grabbedPanel, panels);
+  const grabbedIndex = fullGroup.indexOf(grabbedPanel);
+
+  // Walk left from the grabbed panel, stopping before any pinned panel
+  const leftPanels: PanelState[] = [];
+  for (let i = grabbedIndex; i >= 0; i--) {
+    if (fullGroup[i].isPinned) {
+      // Sever the bond between this pinned panel and the next moveable panel
+      unsnap(fullGroup[i], fullGroup[i + 1]);
+      break;
+    }
+    leftPanels.unshift(fullGroup[i]);
+  }
+
+  // Walk right from the grabbed panel, stopping before any pinned panel
+  const rightPanels: PanelState[] = [];
+  for (let i = grabbedIndex + 1; i < fullGroup.length; i++) {
+    if (fullGroup[i].isPinned) {
+      // Sever the bond between the last moveable panel and this pinned panel
+      unsnap(fullGroup[i - 1], fullGroup[i]);
+      break;
+    }
+    rightPanels.push(fullGroup[i]);
+  }
+
+  return [...leftPanels, ...rightPanels];
+}
+
 /**
  * Break the snap relationship between two specific panels
  */