@blorkfield/blork-tabs 0.2.6 → 0.3.0

package/README.md

@@ -8,6 +8,7 @@ A framework-agnostic tab/panel management system with snapping and docking capab
 - **Anchor Docking** - Dock panels to predefined screen positions
 - **Drag Modes** - Drag entire groups or detach individual panels
 - **Collapse/Expand** - Panels can be collapsed with automatic repositioning
+- **Auto-Hide** - Panels can hide after inactivity and show on interaction
 - **Event System** - Subscribe to drag, snap, and collapse events
 - **Fully Typed** - Complete TypeScript support
 - **Framework Agnostic** - Works with plain DOM or any framework
@@ -89,6 +90,12 @@ const manager = new TabManager({
 
   // CSS class prefix (default: 'blork-tabs')
   classPrefix: 'blork-tabs',
+
+  // Whether panels start hidden (default: false)
+  startHidden: false,
+
+  // Milliseconds before auto-hiding on inactivity (default: undefined = no auto-hide)
+  autoHideDelay: undefined,
 });
 ```
 
@@ -98,6 +105,7 @@ const manager = new TabManager({
 
 #### Panel Management
 - `addPanel(config)` - Create a new panel
+- `addDebugPanel(config)` - Create a debug panel with logging interface
 - `registerPanel(id, element, options)` - Register existing DOM element
 - `removePanel(id)` - Remove a panel
 - `getPanel(id)` - Get panel by ID
@@ -120,6 +128,11 @@ const manager = new TabManager({
 - `removeAnchor(id)` - Remove anchor
 - `getAnchors()` - Get all anchors
 
+#### Auto-Hide
+- `show(panelId)` - Show a hidden panel
+- `hide(panelId)` - Hide a panel
+- `isHidden(panelId)` - Check if panel is hidden
+
 #### Events
 - `on(event, listener)` - Subscribe to event
 - `off(event, listener)` - Unsubscribe from event
@@ -137,6 +150,8 @@ const manager = new TabManager({
 | `snap:anchor` | Panels snapped to anchor |
 | `panel:detached` | Panel detached from chain |
 | `panel:collapse` | Panel collapsed/expanded |
+| `panel:show` | Panel became visible (auto-hide) |
+| `panel:hide` | Panel became hidden (auto-hide) |
 
 ## Multi-Section Panel Content
 
@@ -172,6 +187,153 @@ manager.addPanel({
 
 The panel content area has a max-height (default `20vh`) with `overflow-y: auto`, so long content scrolls properly. Splitting sections across multiple content wrappers defeats this behavior.
 
+## Auto-Hide
+
+Panels can automatically hide after a period of inactivity and reappear when the user interacts with the page. This is useful for OBS overlays or any interface where you want panels to get out of the way.
+
+### Configuration
+
+Auto-hide has two independent options:
+
+- **`startHidden`** - Whether the panel starts invisible (default: `false`)
+- **`autoHideDelay`** - Milliseconds before hiding after inactivity (default: `undefined` = no auto-hide)
+
+These can be set globally on the TabManager or per-panel:
+
+```typescript
+// Global: all panels hide after 3 seconds of inactivity
+const manager = new TabManager({
+  autoHideDelay: 3000,
+  startHidden: true,
+});
+
+// Per-panel overrides
+manager.addPanel({
+  id: 'always-visible',
+  title: 'Always Visible',
+  autoHideDelay: 0,  // Disable auto-hide for this panel
+});
+
+manager.addPanel({
+  id: 'quick-hide',
+  title: 'Quick Hide',
+  autoHideDelay: 1000,  // This panel hides faster
+  startHidden: false,   // But starts visible
+});
+```
+
+### Behavior Matrix
+
+| startHidden | autoHideDelay | Behavior |
+|-------------|---------------|----------|
+| `false` | `undefined` | Normal - always visible |
+| `true` | `undefined` | Starts hidden, shows on activity, never hides again |
+| `false` | `3000` | Starts visible, hides after 3s of inactivity |
+| `true` | `3000` | Starts hidden, shows on activity, hides after 3s of inactivity |
+
+### Events
+
+```typescript
+manager.on('panel:show', ({ panel, trigger }) => {
+  // trigger: 'activity' (user interaction) or 'api' (programmatic)
+  console.log(`${panel.id} is now visible`);
+});
+
+manager.on('panel:hide', ({ panel, trigger }) => {
+  // trigger: 'timeout' (auto-hide delay) or 'api' (programmatic)
+  console.log(`${panel.id} is now hidden`);
+});
+```
+
+### Programmatic Control
+
+```typescript
+manager.hide('my-panel');  // Hide immediately
+manager.show('my-panel');  // Show immediately
+manager.isHidden('my-panel');  // Check visibility
+```
+
+## Debug Panel
+
+A plug-and-play debug panel for in-browser event logging—useful for OBS browser sources and other environments without console access.
+
+### Creating a Debug Panel
+
+```typescript
+import { TabManager } from '@blorkfield/blork-tabs';
+
+const manager = new TabManager();
+
+// Create a debug panel
+const debug = manager.addDebugPanel({
+  id: 'debug',
+  title: 'Event Log',        // optional, default: 'Debug'
+  width: 300,                // optional, default: 300
+  maxEntries: 50,            // optional, default: 50
+  showTimestamps: true,      // optional, default: false
+  showClearButton: true,     // optional, default: true
+  startCollapsed: true,      // optional, default: true
+  initialPosition: { x: 16, y: 16 },
+});
+```
+
+### Logging Events
+
+Log events with different severity levels, each with distinct color coding:
+
+```typescript
+// Info/Log level - blue (accent color)
+debug.log('event-name', { some: 'data' });
+debug.info('connection', { status: 'connected' });
+
+// Warning level - yellow
+debug.warn('cache', { message: 'Cache expired, refreshing...' });
+
+// Error level - red
+debug.error('request', { code: 500, message: 'Server error' });
+
+// Clear all entries
+debug.clear();
+```
+
+### Features
+
+- **Pre-styled monospace container** - Optimized for log readability
+- **Color-coded log levels** - Blue for info, yellow for warnings, red for errors
+- **Auto-scroll** - Automatically scrolls to show latest entries
+- **Entry limit** - Configurable max entries with FIFO removal of oldest
+- **Timestamps** - Optional timestamp display for each entry
+- **Hover glow effect** - Border lights up with accent color on hover
+- **Enlarge on hover** - Hover for 5 seconds to expand to 75% of screen with 2x text size
+- **Modal backdrop** - Enlarged view has a backdrop; click × or backdrop to close
+- **Standard panel features** - Drag, snap, collapse, auto-hide all work
+
+### Enlarged View Behavior
+
+The debug panel has a special "focus mode" for reading logs:
+
+1. **Hover for 5 seconds** → Panel enlarges to 75% of screen with doubled text size
+2. **Mouse can move freely** → Panel stays enlarged, won't close on mouse leave
+3. **Click × or backdrop** → Returns to normal size
+
+The × button is only visible when enlarged.
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maxEntries` | `number` | `50` | Maximum log entries before oldest are removed |
+| `showTimestamps` | `boolean` | `false` | Show timestamps on each entry |
+
+Plus all standard `PanelConfig` options (`id`, `title`, `width`, `initialPosition`, `startCollapsed`, etc.)
+
+### Accessing the Underlying Panel
+
+```typescript
+// The debug panel interface includes access to the panel state
+debug.panel;  // PanelState - for advanced manipulation
+```
+
 ## CSS Customization
 
 Override CSS variables to customize appearance:

package/dist/index.cjs

@@ -21,10 +21,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AnchorManager: () => AnchorManager,
+  AutoHideManager: () => AutoHideManager,
   DragManager: () => DragManager,
   SnapPreview: () => SnapPreview,
   TabManager: () => TabManager,
   areInSameChain: () => areInSameChain,
+  createDebugPanelContent: () => createDebugPanelContent,
+  createDebugPanelInterface: () => createDebugPanelInterface,
   createPanelElement: () => createPanelElement,
   createPanelState: () => createPanelState,
   createPresetAnchor: () => createPresetAnchor,
@@ -38,8 +41,10 @@ __export(index_exports, {
   getPanelDimensions: () => getPanelDimensions,
   getPanelPosition: () => getPanelPosition,
   getRightmostPanel: () => getRightmostPanel,
+  hidePanel: () => hidePanel,
   setPanelPosition: () => setPanelPosition,
   setPanelZIndex: () => setPanelZIndex,
+  showPanel: () => showPanel,
   snapPanels: () => snapPanels,
   snapPanelsToTarget: () => snapPanelsToTarget,
   toggleCollapse: () => toggleCollapse,
@@ -48,6 +53,64 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/DebugPanel.ts
+function createDebugPanelContent(_config, classes) {
+  const content = document.createElement("div");
+  const logContainer = document.createElement("div");
+  logContainer.className = classes.debugLog;
+  content.appendChild(logContainer);
+  return {
+    content,
+    elements: { logContainer, clearButton: null }
+  };
+}
+function createDebugPanelInterface(panel, elements, config, classes) {
+  const maxEntries = config.maxEntries ?? 50;
+  const showTimestamps = config.showTimestamps ?? false;
+  function addEntry(level, eventName, data) {
+    const entry = document.createElement("div");
+    entry.className = classes.debugLogEntry;
+    if (level === "warn") entry.classList.add(classes.debugLogEntryWarn);
+    if (level === "error") entry.classList.add(classes.debugLogEntryError);
+    let html = "";
+    if (showTimestamps) {
+      const time = (/* @__PURE__ */ new Date()).toLocaleTimeString("en-US", {
+        hour12: false,
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit"
+      });
+      html += `<span class="${classes.debugLogTimestamp}">${time}</span>`;
+    }
+    html += `<span class="${classes.debugLogName}">${escapeHtml(eventName)}</span>`;
+    if (data) {
+      const dataStr = JSON.stringify(data);
+      html += `<span class="${classes.debugLogData}">${escapeHtml(dataStr)}</span>`;
+    }
+    entry.innerHTML = html;
+    elements.logContainer.appendChild(entry);
+    elements.logContainer.scrollTop = elements.logContainer.scrollHeight;
+    while (elements.logContainer.children.length > maxEntries) {
+      elements.logContainer.removeChild(elements.logContainer.children[0]);
+    }
+  }
+  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 = "";
+    }
+  };
+}
+function escapeHtml(str) {
+  const div = document.createElement("div");
+  div.textContent = str;
+  return div.innerHTML;
+}
+
 // src/Panel.ts
 function createPanelElement(config, classes) {
   const element = document.createElement("div");
@@ -102,7 +165,7 @@ function createPanelElement(config, classes) {
     detachGrip
   };
 }
-function createPanelState(config, classes) {
+function createPanelState(config, classes, globalConfig) {
   let element;
   let dragHandle;
   let collapseButton;
@@ -122,6 +185,11 @@ function createPanelState(config, classes) {
     contentWrapper = created.contentWrapper;
     detachGrip = created.detachGrip;
   }
+  const resolvedStartHidden = config.startHidden ?? globalConfig?.startHidden ?? false;
+  const resolvedAutoHideDelay = config.autoHideDelay !== void 0 ? config.autoHideDelay === 0 ? void 0 : config.autoHideDelay : globalConfig?.autoHideDelay;
+  if (resolvedStartHidden) {
+    element.classList.add(classes.panelHidden);
+  }
   return {
     id: config.id,
     element,
@@ -132,7 +200,9 @@ function createPanelState(config, classes) {
     isCollapsed: config.startCollapsed !== false,
     snappedTo: null,
     snappedFrom: null,
-    config
+    config,
+    isHidden: resolvedStartHidden,
+    resolvedAutoHideDelay
   };
 }
 function toggleCollapse(state, classes, collapsed) {
@@ -148,6 +218,16 @@ function toggleCollapse(state, classes, collapsed) {
   }
   return newState;
 }
+function showPanel(state, classes) {
+  if (!state.isHidden) return;
+  state.isHidden = false;
+  state.element.classList.remove(classes.panelHidden);
+}
+function hidePanel(state, classes) {
+  if (state.isHidden) return;
+  state.isHidden = true;
+  state.element.classList.add(classes.panelHidden);
+}
 function setPanelPosition(state, x, y) {
   state.element.style.left = `${x}px`;
   state.element.style.top = `${y}px`;
@@ -817,6 +897,109 @@ var SnapPreview = class {
   }
 };
 
+// src/AutoHideManager.ts
+var AutoHideManager = class {
+  constructor(panels, classes, callbacks) {
+    this.hideTimers = /* @__PURE__ */ new Map();
+    this.listenersAttached = false;
+    this.panels = panels;
+    this.classes = classes;
+    this.callbacks = callbacks;
+    this.boundActivityHandler = this.handleActivity.bind(this);
+  }
+  /**
+   * Attach activity listeners to document
+   */
+  attachListeners() {
+    if (this.listenersAttached) return;
+    document.addEventListener("mousemove", this.boundActivityHandler);
+    document.addEventListener("mousedown", this.boundActivityHandler);
+    document.addEventListener("keydown", this.boundActivityHandler);
+    this.listenersAttached = true;
+  }
+  /**
+   * Handle user activity - show hidden panels and reset timers
+   */
+  handleActivity() {
+    for (const panel of this.panels.values()) {
+      if (panel.resolvedAutoHideDelay !== void 0 || panel.isHidden) {
+        this.show(panel, "activity");
+        if (panel.resolvedAutoHideDelay !== void 0) {
+          this.scheduleHide(panel);
+        }
+      }
+    }
+  }
+  /**
+   * Schedule a panel to hide after its delay
+   */
+  scheduleHide(panel) {
+    this.clearTimer(panel.id);
+    if (panel.resolvedAutoHideDelay === void 0) return;
+    const timer = setTimeout(() => {
+      this.hide(panel, "timeout");
+    }, panel.resolvedAutoHideDelay);
+    this.hideTimers.set(panel.id, timer);
+  }
+  /**
+   * Clear hide timer for a panel
+   */
+  clearTimer(panelId) {
+    const timer = this.hideTimers.get(panelId);
+    if (timer) {
+      clearTimeout(timer);
+      this.hideTimers.delete(panelId);
+    }
+  }
+  /**
+   * Show a panel
+   */
+  show(panel, trigger) {
+    if (!panel.isHidden) return;
+    showPanel(panel, this.classes);
+    this.callbacks.onShow?.(panel, trigger);
+  }
+  /**
+   * Hide a panel
+   */
+  hide(panel, trigger) {
+    if (panel.isHidden) return;
+    hidePanel(panel, this.classes);
+    this.callbacks.onHide?.(panel, trigger);
+  }
+  /**
+   * Initialize a newly added panel's auto-hide state
+   */
+  initializePanel(panel) {
+    if (panel.resolvedAutoHideDelay !== void 0 || panel.isHidden) {
+      this.attachListeners();
+    }
+    if (!panel.isHidden && panel.resolvedAutoHideDelay !== void 0) {
+      this.scheduleHide(panel);
+    }
+  }
+  /**
+   * Clean up when a panel is removed
+   */
+  cleanupPanel(panelId) {
+    this.clearTimer(panelId);
+  }
+  /**
+   * Clean up all resources
+   */
+  destroy() {
+    if (this.listenersAttached) {
+      document.removeEventListener("mousemove", this.boundActivityHandler);
+      document.removeEventListener("mousedown", this.boundActivityHandler);
+      document.removeEventListener("keydown", this.boundActivityHandler);
+    }
+    for (const timer of this.hideTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.hideTimers.clear();
+  }
+};
+
 // src/TabManager.ts
 var DEFAULT_CONFIG = {
   snapThreshold: 50,
@@ -826,7 +1009,9 @@ var DEFAULT_CONFIG = {
   defaultPanelWidth: 300,
   container: document.body,
   initializeDefaultAnchors: true,
-  classPrefix: "blork-tabs"
+  classPrefix: "blork-tabs",
+  startHidden: false,
+  autoHideDelay: void 0
 };
 function generateClasses(prefix) {
   return {
@@ -842,13 +1027,27 @@ function generateClasses(prefix) {
     anchorIndicator: `${prefix}-anchor-indicator`,
     anchorIndicatorVisible: `${prefix}-anchor-indicator-visible`,
     anchorIndicatorActive: `${prefix}-anchor-indicator-active`,
-    dragging: `${prefix}-dragging`
+    dragging: `${prefix}-dragging`,
+    panelHidden: `${prefix}-panel-hidden`,
+    debugLog: `${prefix}-debug-log`,
+    debugLogEntry: `${prefix}-debug-log-entry`,
+    debugLogEntryInfo: `${prefix}-debug-log-entry-info`,
+    debugLogEntryWarn: `${prefix}-debug-log-entry-warn`,
+    debugLogEntryError: `${prefix}-debug-log-entry-error`,
+    debugLogName: `${prefix}-debug-log-name`,
+    debugLogData: `${prefix}-debug-log-data`,
+    debugLogTimestamp: `${prefix}-debug-log-timestamp`,
+    debugClearButton: `${prefix}-debug-clear-btn`,
+    debugPanel: `${prefix}-debug-panel`,
+    debugPanelEnlarged: `${prefix}-debug-panel-enlarged`,
+    debugBackdrop: `${prefix}-debug-backdrop`
   };
 }
 var TabManager = class {
   constructor(userConfig = {}) {
     this.panels = /* @__PURE__ */ new Map();
     this.eventListeners = /* @__PURE__ */ new Map();
+    this.debugPanelElements = /* @__PURE__ */ new Map();
     this.config = {
       ...DEFAULT_CONFIG,
       ...userConfig,
@@ -871,6 +1070,14 @@ var TabManager = class {
         findAnchorTarget: (panels) => this.anchorManager.findNearestAnchor(panels)
       }
     );
+    this.autoHideManager = new AutoHideManager(
+      this.panels,
+      this.classes,
+      {
+        onShow: (panel, trigger) => this.emit("panel:show", { panel, trigger }),
+        onHide: (panel, trigger) => this.emit("panel:hide", { panel, trigger })
+      }
+    );
     if (this.config.initializeDefaultAnchors) {
       this.anchorManager.addDefaultAnchors();
     }
@@ -880,7 +1087,10 @@ var TabManager = class {
    * Add a new panel
    */
   addPanel(panelConfig) {
-    const state = createPanelState(panelConfig, this.classes);
+    const state = createPanelState(panelConfig, this.classes, {
+      startHidden: this.config.startHidden,
+      autoHideDelay: this.config.autoHideDelay
+    });
     if (!panelConfig.element && !this.config.container.contains(state.element)) {
       this.config.container.appendChild(state.element);
     }
@@ -889,6 +1099,7 @@ var TabManager = class {
     if (panelConfig.initialPosition) {
       setPanelPosition(state, panelConfig.initialPosition.x, panelConfig.initialPosition.y);
     }
+    this.autoHideManager.initializePanel(state);
     this.emit("panel:added", { panel: state });
     return state;
   }
@@ -912,6 +1123,8 @@ var TabManager = class {
   removePanel(id) {
     const panel = this.panels.get(id);
     if (!panel) return false;
+    this.autoHideManager.cleanupPanel(id);
+    this.debugPanelElements.delete(id);
     detachFromGroup(panel, this.panels);
     if (!panel.config.element) {
       panel.element.remove();
@@ -932,6 +1145,70 @@ var TabManager = class {
   getAllPanels() {
     return Array.from(this.panels.values());
   }
+  /**
+   * Add a debug panel with built-in logging functionality
+   */
+  addDebugPanel(config) {
+    const { content, elements } = createDebugPanelContent(config, this.classes);
+    const panelConfig = {
+      ...config,
+      title: config.title ?? "Debug",
+      content,
+      startCollapsed: config.startCollapsed ?? true
+    };
+    const state = this.addPanel(panelConfig);
+    state.element.classList.add(this.classes.debugPanel);
+    const closeBtn = document.createElement("button");
+    closeBtn.className = this.classes.debugClearButton;
+    closeBtn.textContent = "\xD7";
+    closeBtn.title = "Close enlarged view";
+    if (state.collapseButton) {
+      state.collapseButton.parentElement?.insertBefore(closeBtn, state.collapseButton);
+    }
+    elements.clearButton = closeBtn;
+    this.debugPanelElements.set(state.id, elements);
+    const debugPanel = createDebugPanelInterface(state, elements, config, this.classes);
+    let hoverTimeout = null;
+    let isEnlarged = false;
+    let backdrop = null;
+    const enlargedClass = this.classes.debugPanelEnlarged;
+    const backdropClass = this.classes.debugBackdrop;
+    const closeEnlarged = () => {
+      if (!isEnlarged) return;
+      isEnlarged = false;
+      state.element.classList.remove(enlargedClass);
+      if (backdrop) {
+        backdrop.remove();
+        backdrop = null;
+      }
+    };
+    const openEnlarged = () => {
+      if (isEnlarged) return;
+      isEnlarged = true;
+      backdrop = document.createElement("div");
+      backdrop.className = backdropClass;
+      this.config.container.appendChild(backdrop);
+      backdrop.addEventListener("click", closeEnlarged);
+      state.element.classList.add(enlargedClass);
+    };
+    state.element.addEventListener("mouseenter", () => {
+      if (isEnlarged) return;
+      hoverTimeout = setTimeout(() => {
+        openEnlarged();
+      }, 5e3);
+    });
+    state.element.addEventListener("mouseleave", () => {
+      if (hoverTimeout) {
+        clearTimeout(hoverTimeout);
+        hoverTimeout = null;
+      }
+    });
+    closeBtn.addEventListener("click", (e) => {
+      e.stopPropagation();
+      closeEnlarged();
+    });
+    return debugPanel;
+  }
   /**
    * Set up event handlers for a panel
    */
@@ -1017,6 +1294,31 @@ var TabManager = class {
   getAnchors() {
     return this.anchorManager.getAnchors();
   }
+  // ==================== Auto-Hide ====================
+  /**
+   * Show a hidden panel
+   */
+  show(panelId) {
+    const panel = this.panels.get(panelId);
+    if (!panel) return false;
+    this.autoHideManager.show(panel, "api");
+    return true;
+  }
+  /**
+   * Hide a panel
+   */
+  hide(panelId) {
+    const panel = this.panels.get(panelId);
+    if (!panel) return false;
+    this.autoHideManager.hide(panel, "api");
+    return true;
+  }
+  /**
+   * Check if a panel is hidden
+   */
+  isHidden(panelId) {
+    return this.panels.get(panelId)?.isHidden ?? false;
+  }
   // ==================== Drag Callbacks ====================
   handleDragStart(state) {
     this.anchorManager.showIndicators(null);
@@ -1155,6 +1457,7 @@ var TabManager = class {
     this.dragManager.destroy();
     this.anchorManager.destroy();
     this.snapPreview.destroy();
+    this.autoHideManager.destroy();
     for (const panel of this.panels.values()) {
       if (!panel.config.element) {
         panel.element.remove();
@@ -1162,15 +1465,19 @@ var TabManager = class {
     }
     this.panels.clear();
     this.eventListeners.clear();
+    this.debugPanelElements.clear();
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AnchorManager,
+  AutoHideManager,
   DragManager,
   SnapPreview,
   TabManager,
   areInSameChain,
+  createDebugPanelContent,
+  createDebugPanelInterface,
   createPanelElement,
   createPanelState,
   createPresetAnchor,
@@ -1184,8 +1491,10 @@ var TabManager = class {
   getPanelDimensions,
   getPanelPosition,
   getRightmostPanel,
+  hidePanel,
   setPanelPosition,
   setPanelZIndex,
+  showPanel,
   snapPanels,
   snapPanelsToTarget,
   toggleCollapse,