@blorkfield/blork-tabs 0.3.0 → 0.4.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
+- **Pin** - Pin panels to prevent dragging and opt out of auto-hide
 - **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
@@ -54,6 +55,7 @@ manager.registerPanel('my-panel', document.getElementById('my-panel'), {
 });
 
 // Position panels and create snap chains
+// positionPanelsFromRight takes IDs right-to-left; createSnapChain takes them left-to-right
 manager.positionPanelsFromRight(['tools', 'settings']);
 manager.createSnapChain(['settings', 'tools']);
 
@@ -99,6 +101,40 @@ const manager = new TabManager({
 });
 ```
 
+## Panel Configuration
+
+Each panel accepts the following options via `addPanel(config)`:
+
+```typescript
+manager.addPanel({
+  id: 'my-panel',           // Required. Unique identifier.
+  title: 'My Panel',        // Header text.
+  width: 300,               // Panel width in px (default: 300).
+  initialPosition: { x: 100, y: 100 },  // Starting position. Auto-placed if omitted.
+  content: '<div>...</div>', // HTML string or HTMLElement for the content area.
+
+  // Collapse
+  startCollapsed: true,     // Whether the panel starts collapsed (default: true).
+  collapsible: true,        // Show collapse button (default: true).
+
+  // Pin
+  pinnable: false,          // Show pin button in header (default: false).
+  startPinned: false,       // Initial pin state (default: false).
+
+  // Drag
+  draggable: true,          // Allow dragging (default: true).
+  detachable: true,         // Show detach grip for single-panel drag (default: true).
+
+  // Auto-hide overrides (see Auto-Hide section)
+  startHidden: false,       // Override global startHidden for this panel.
+  autoHideDelay: undefined, // Override global autoHideDelay (0 = disable auto-hide).
+
+  // Z-index
+  zIndex: 1000,             // Default z-index (default: 1000).
+  dragZIndex: 1002,         // Z-index while dragging (default: 1002).
+});
+```
+
 ## API Reference
 
 ### TabManager
@@ -115,12 +151,23 @@ const manager = new TabManager({
 - `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
+- `createSnapChain(panelIds)` - Create chain from panel IDs (left-to-right order)
 - `updatePositions()` - Recalculate snapped positions
 
 #### Positioning
-- `positionPanelsFromRight(panelIds, gap?)` - Position from right edge
-- `positionPanelsFromLeft(panelIds, gap?)` - Position from left edge
+
+`positionPanelsFromRight` and `positionPanelsFromLeft` take panel IDs in **opposite orders**:
+
+- `positionPanelsFromRight(panelIds, gap?)` — first ID is placed at the **right edge**, rest go leftward. Pass IDs **right-to-left**.
+- `positionPanelsFromLeft(panelIds, gap?)` — first ID is placed at the **left edge**, rest go rightward. Pass IDs **left-to-right**.
+
+Because `createSnapChain` uses left-to-right order, you'll typically reverse the array between the two calls:
+
+```typescript
+// Visual order left-to-right: properties, tools, settings
+manager.positionPanelsFromRight(['settings', 'tools', 'properties']); // right-to-left
+manager.createSnapChain(['properties', 'tools', 'settings']);          // left-to-right
+```
 
 #### Anchors
 - `addAnchor(config)` - Add custom anchor
@@ -149,10 +196,54 @@ const manager = new TabManager({
 | `snap:panel` | Panels snapped together |
 | `snap:anchor` | Panels snapped to anchor |
 | `panel:detached` | Panel detached from chain |
+| `panel:pin` | Panel pinned/unpinned |
 | `panel:collapse` | Panel collapsed/expanded |
 | `panel:show` | Panel became visible (auto-hide) |
 | `panel:hide` | Panel became hidden (auto-hide) |
 
+## Drag Modes
+
+Each panel header has two drag zones:
+
+- **Detach grip** (small handle on the left of the header) — drags only that panel. It is detached from its snap chain and moved independently.
+- **Title / header area** — drags the entire connected snap chain as a group.
+
+Set `detachable: false` to hide the grip and make the header always drag the group.
+
+## Pinning
+
+Pinning locks a panel in place and exempts it from auto-hide. Enable the pin button with `pinnable: true`:
+
+```typescript
+manager.addPanel({
+  id: 'hud',
+  title: 'HUD',
+  pinnable: true,
+  startPinned: true,   // start already pinned
+  autoHideDelay: 5000, // pin will override this
+});
+```
+
+### What pinning does
+
+- **Prevents dragging** — a pinned panel cannot be moved, even when dragging its header.
+- **Immune to auto-hide** — a pinned panel is always visible regardless of the `autoHideDelay`. Pinning cancels any pending hide timer and shows the panel if it was hidden. Unpinning restarts the timer.
+- **Splits snap chains on drag** — if a pinned panel sits in the middle of a chain and you drag a neighbour, the chain severs at the pin boundary. Only the panels on the same side as the grabbed panel move; the pinned panel and everything beyond it stay put.
+
+```typescript
+// Chain: A — B — [P pinned] — C — D
+// Grabbing B moves [A, B] and severs the B↔P bond.
+// Grabbing C moves [C, D] and severs the P↔C bond.
+```
+
+### Events
+
+```typescript
+manager.on('panel:pin', ({ panel, isPinned }) => {
+  console.log(`${panel.id} is now ${isPinned ? 'pinned' : 'unpinned'}`);
+});
+```
+
 ## 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.
@@ -231,6 +322,10 @@ manager.addPanel({
 | `false` | `3000` | Starts visible, hides after 3s of inactivity |
 | `true` | `3000` | Starts hidden, shows on activity, hides after 3s of inactivity |
 
+### Pin interaction
+
+Pinning a panel overrides auto-hide entirely for that panel — it stays visible regardless of inactivity. Unpinning re-enables the timer. Each panel is tracked independently; pinning one panel in a group has no effect on its neighbours.
+
 ### Events
 
 ```typescript
@@ -312,11 +407,13 @@ debug.clear();
 
 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
+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.
+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
 
@@ -324,6 +421,7 @@ The × button is only visible when enlarged.
 |--------|------|---------|-------------|
 | `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.)
 
@@ -334,6 +432,41 @@ Plus all standard `PanelConfig` options (`id`, `title`, `width`, `initialPositio
 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: