A framework-agnostic tab/panel management system with snapping and docking
npm install @blorkfield/blork-tabsA framework-agnostic tab/panel management system with snapping and docking capabilities.
- 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
``bash`
npm install @blorkfield/blork-tabs
`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: '
manager.addPanel({
id: 'tools',
title: 'Tools',
content: '
// Or register existing DOM elements
manager.registerPanel('my-panel', document.getElementById('my-panel'), {
dragHandle: document.getElementById('my-panel-header'),
collapseButton: document.getElementById('my-panel-collapse'),
contentWrapper: document.getElementById('my-panel-content'),
});
// Position panels and create snap chains
manager.positionPanelsFromRight(['tools', 'settings']);
manager.createSnapChain(['settings', 'tools']);
// Listen to events
manager.on('snap:panel', ({ movingPanels, targetPanel, side }) => {
console.log(Panels snapped to ${side} of ${targetPanel.id});`
});
`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,
});
`
#### Panel Management
- addPanel(config) - Create a new paneladdDebugPanel(config)
- - Create a debug panel with logging interfaceregisterPanel(id, element, options)
- - Register existing DOM elementremovePanel(id)
- - Remove a panelgetPanel(id)
- - Get panel by IDgetAllPanels()
- - Get all panels
#### Snap Chain Management
- getSnapChain(panelId) - Get all panels in same chainsnap(leftPanelId, rightPanelId)
- - Manually snap two panelsdetach(panelId)
- - Detach panel from chaincreateSnapChain(panelIds)
- - Create chain from panel IDsupdatePositions()
- - Recalculate snapped positions
#### Positioning
- positionPanelsFromRight(panelIds, gap?) - Position from right edgepositionPanelsFromLeft(panelIds, gap?)
- - Position from left edge
#### Anchors
- addAnchor(config) - Add custom anchoraddPresetAnchor(preset)
- - Add preset anchorremoveAnchor(id)
- - Remove anchorgetAnchors()
- - Get all anchors
#### Auto-Hide
- show(panelId) - Show a hidden panelhide(panelId)
- - Hide a panelisHidden(panelId)
- - Check if panel is hidden
#### Events
- on(event, listener) - Subscribe to eventoff(event, listener)
- - Unsubscribe from event
| 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) |
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 sizeThe × 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: '
Some content',
});// 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:
`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
``MIT