@blorkfield/blork-tabs

A framework-agnostic tab/panel management system with snapping and docking capabilities.

Features

- Panel Snapping - Panels snap together to form linked chains
- 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
- Customizable - CSS variables for easy theming

Installation

``bash
npm install @blorkfield/blork-tabs
`

Quick Start

`typescript
import { TabManager } from '@blorkfield/blork-tabs';
import '@blorkfield/blork-tabs/styles.css';

// Create the tab manager
const manager = new TabManager({
snapThreshold: 50,
panelGap: 0,
panelMargin: 16,
});

// Create panels programmatically
manager.addPanel({
id: 'settings',
title: 'Settings',
content: '

// Listen to events
manager.on('snap:panel', ({ movingPanels, targetPanel, side }) => {
console.log(Panels snapped to ${side} of ${targetPanel.id});
});
`

Configuration

`typescript
const manager = new TabManager({
// Distance threshold for panel-to-panel snapping (default: 50)
snapThreshold: 50,

// Gap between snapped panels (default: 0)
panelGap: 0,

// Margin from window edges (default: 16)
panelMargin: 16,

// Distance threshold for anchor snapping (default: 80)
anchorThreshold: 80,

// Default panel width for calculations (default: 300)
defaultPanelWidth: 300,

// Container element (default: document.body)
container: document.body,

// Auto-create default anchors (default: true)
initializeDefaultAnchors: true,

// 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,
});
`

API Reference

$3

#### 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
- getAllPanels() - Get all panels

#### Snap Chain Management
- getSnapChain(panelId) - Get all panels in same chain
- snap(leftPanelId, rightPanelId) - Manually snap two panels
- detach(panelId) - Detach panel from chain
- createSnapChain(panelIds) - Create chain from panel IDs
- updatePositions() - Recalculate snapped positions

#### Positioning
- positionPanelsFromRight(panelIds, gap?) - Position from right edge
- positionPanelsFromLeft(panelIds, gap?) - Position from left edge

#### Anchors
- addAnchor(config) - Add custom anchor
- addPresetAnchor(preset) - Add preset anchor
- 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

$3

| Event | Description |
|-------|-------------|
| panel:added | Panel was added |
| panel:removed | Panel was removed |
| drag:start | Drag operation started |
| drag:move | Panel being dragged |
| drag:end | Drag operation ended |
| snap:panel | Panels snapped together |
| 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

When creating panels with multiple sections (like a command menu with categories), put all sections within a single content string. Do not use multiple panels or multiple content wrappers—this breaks scrolling and causes content cutoff.

Correct approach:

`typescript
manager.addPanel({
id: 'command-menu',
title: 'Commands',
content:

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.

$3

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
});
`

$3

| 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 |

$3

`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);
});
`

$3

`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.

$3

`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 },
});
`

$3

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();
`

$3

- 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

$3

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.

$3

| 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.)

$3

`typescript
// The debug panel interface includes access to the panel state
debug.panel; // PanelState - for advanced manipulation
`

$3

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: '

// 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:

`css
:root {
--blork-tabs-panel-bg: #1a1a2e;
--blork-tabs-panel-border: 1px solid #2a2a4a;
--blork-tabs-panel-radius: 8px;
--blork-tabs-panel-shadow: 0 4px 20px rgba(0, 0, 0, 0.4);
--blork-tabs-header-bg: #2a2a4a;
--blork-tabs-header-color: #e0e0e0;
--blork-tabs-content-bg: #1a1a2e;
--blork-tabs-content-max-height: 20vh;
--blork-tabs-accent: #4a90d9;
}
`

For light theme, add blork-tabs-light class to container:

`html

``

License

MIT