@blorkfield/blork-tabs 0.2.6 → 0.3.1

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,191 @@ 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 configurable delay** → Panel enlarges to 75% of screen with doubled text size (default: 5 seconds, configurable via `hoverDelay`)
+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. Set `hoverDelay: 0` to disable the enlarge feature entirely.
+
+**Auto-hide interaction:** When hovering a debug panel that has auto-hide enabled, the auto-hide timer is paused so the panel won't disappear before the hover-to-enlarge triggers.
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maxEntries` | `number` | `50` | Maximum log entries before oldest are removed |
+| `showTimestamps` | `boolean` | `false` | Show timestamps on each entry |
+| `hoverDelay` | `number` | `5000` | Milliseconds to hover before enlarging (0 = disable) |
+
+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
+```
+
+### Embeddable Debug Log
+
+You can embed a debug log inside any panel or container element using `createDebugLog()`:
+
+```typescript
+const manager = new TabManager();
+
+// Create a panel with custom content
+const panel = manager.addPanel({
+  id: 'my-panel',
+  title: 'My Panel',
+  content: '<div id="my-content">Some content</div>',
+});
+
+// Add a debug log section to the panel
+const logSection = document.createElement('div');
+panel.contentWrapper.appendChild(logSection);
+
+// Create the embedded debug log (shares hover-to-enlarge with standalone panels)
+const embeddedLog = manager.createDebugLog(logSection, {
+  maxEntries: 20,
+  showTimestamps: true,
+  hoverDelay: 3000,  // 3 second hover delay (0 to disable, default: 5000)
+});
+
+// Use it like a regular debug panel
+embeddedLog.log('event', { data: 'value' });
+embeddedLog.info('status', { connected: true });
+embeddedLog.warn('warning', { message: 'Low memory' });
+embeddedLog.error('error', { code: 500 });
+embeddedLog.clear();
+```
+
+The embedded log supports the same hover-to-enlarge behavior as the standalone debug panel.
+
 ## CSS Customization
 
 Override CSS variables to customize appearance: