@blorkfield/blork-tabs 0.3.1 → 0.5.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

package/dist/index.cjs

@@ -32,6 +32,7 @@ __export(index_exports, {
   createPanelElement: () => createPanelElement,
   createPanelState: () => createPanelState,
   createPresetAnchor: () => createPresetAnchor,
+  createTagButton: () => createTagButton,
   detachFromGroup: () => detachFromGroup,
   findSnapTarget: () => findSnapTarget,
   getConnectedGroup: () => getConnectedGroup,
@@ -39,6 +40,7 @@ __export(index_exports, {
   getDefaultZIndex: () => getDefaultZIndex,
   getDragZIndex: () => getDragZIndex,
   getLeftmostPanel: () => getLeftmostPanel,
+  getMovingGroupRespectingPins: () => getMovingGroupRespectingPins,
   getPanelDimensions: () => getPanelDimensions,
   getPanelPosition: () => getPanelPosition,
   getRightmostPanel: () => getRightmostPanel,
@@ -50,6 +52,7 @@ __export(index_exports, {
   snapPanels: () => snapPanels,
   snapPanelsToTarget: () => snapPanelsToTarget,
   toggleCollapse: () => toggleCollapse,
+  togglePin: () => togglePin,
   unsnap: () => unsnap,
   updateSnappedPositions: () => updateSnappedPositions
 });
@@ -199,6 +202,8 @@ function setupHoverEnlarge(config) {
 }
 
 // src/Panel.ts
+var PIN_ICON_UNPINNED = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="display:block"><line x1="12" y1="17" x2="12" y2="22"/><path d="M5 17H19V16L17 11V4H7L5 11V16Z"/><line x1="5" y1="11" x2="19" y2="11"/></svg>`;
+var PIN_ICON_PINNED = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="14" height="14" fill="currentColor" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="display:block;transform:rotate(90deg)"><line x1="12" y1="17" x2="12" y2="22"/><path d="M5 17H19V16L17 11V4H7L5 11V16Z"/><line x1="5" y1="11" x2="19" y2="11"/></svg>`;
 function createPanelElement(config, classes) {
   const element = document.createElement("div");
   element.className = classes.panel;
@@ -221,6 +226,14 @@ function createPanelElement(config, classes) {
     title.textContent = config.title;
     header.appendChild(title);
   }
+  let pinButton = null;
+  if (config.pinnable === true) {
+    pinButton = document.createElement("button");
+    pinButton.className = classes.pinButton;
+    pinButton.id = `${config.id}-pin-btn`;
+    pinButton.innerHTML = config.startPinned === true ? PIN_ICON_PINNED : PIN_ICON_UNPINNED;
+    header.appendChild(pinButton);
+  }
   let collapseButton = null;
   if (config.collapsible !== false) {
     collapseButton = document.createElement("button");
@@ -247,6 +260,7 @@ function createPanelElement(config, classes) {
   return {
     element,
     dragHandle: header,
+    pinButton,
     collapseButton,
     contentWrapper,
     detachGrip
@@ -255,12 +269,14 @@ function createPanelElement(config, classes) {
 function createPanelState(config, classes, globalConfig) {
   let element;
   let dragHandle;
+  let pinButton;
   let collapseButton;
   let contentWrapper;
   let detachGrip;
   if (config.element) {
     element = config.element;
     dragHandle = config.dragHandle ?? element.querySelector(`.${classes.panelHeader}`);
+    pinButton = config.pinButton ?? element.querySelector(`.${classes.pinButton}`);
     collapseButton = config.collapseButton ?? element.querySelector(`.${classes.collapseButton}`);
     contentWrapper = config.contentWrapper ?? element.querySelector(`.${classes.panelContent}`);
     detachGrip = config.detachGrip ?? element.querySelector(`.${classes.detachGrip}`);
@@ -268,6 +284,7 @@ function createPanelState(config, classes, globalConfig) {
     const created = createPanelElement(config, classes);
     element = created.element;
     dragHandle = created.dragHandle;
+    pinButton = created.pinButton;
     collapseButton = created.collapseButton;
     contentWrapper = created.contentWrapper;
     detachGrip = created.detachGrip;
@@ -281,9 +298,11 @@ function createPanelState(config, classes, globalConfig) {
     id: config.id,
     element,
     dragHandle,
+    pinButton,
     collapseButton,
     contentWrapper,
     detachGrip,
+    isPinned: config.startPinned === true,
     isCollapsed: config.startCollapsed !== false,
     snappedTo: null,
     snappedFrom: null,
@@ -305,6 +324,14 @@ function toggleCollapse(state, classes, collapsed) {
   }
   return newState;
 }
+function togglePin(state, pinned) {
+  const newState = pinned ?? !state.isPinned;
+  state.isPinned = newState;
+  if (state.pinButton) {
+    state.pinButton.innerHTML = newState ? PIN_ICON_PINNED : PIN_ICON_UNPINNED;
+  }
+  return newState;
+}
 function showPanel(state, classes) {
   if (!state.isHidden) return;
   state.isHidden = false;
@@ -482,6 +509,28 @@ function snapPanels(leftPanel, rightPanel) {
   leftPanel.snappedTo = rightPanel.id;
   rightPanel.snappedFrom = leftPanel.id;
 }
+function getMovingGroupRespectingPins(grabbedPanel, panels) {
+  if (grabbedPanel.isPinned) return [];
+  const fullGroup = getConnectedGroup(grabbedPanel, panels);
+  const grabbedIndex = fullGroup.indexOf(grabbedPanel);
+  const leftPanels = [];
+  for (let i = grabbedIndex; i >= 0; i--) {
+    if (fullGroup[i].isPinned) {
+      unsnap(fullGroup[i], fullGroup[i + 1]);
+      break;
+    }
+    leftPanels.unshift(fullGroup[i]);
+  }
+  const rightPanels = [];
+  for (let i = grabbedIndex + 1; i < fullGroup.length; i++) {
+    if (fullGroup[i].isPinned) {
+      unsnap(fullGroup[i - 1], fullGroup[i]);
+      break;
+    }
+    rightPanels.push(fullGroup[i]);
+  }
+  return [...leftPanels, ...rightPanels];
+}
 function unsnap(leftPanel, rightPanel) {
   if (leftPanel.snappedTo === rightPanel.id) {
     leftPanel.snappedTo = null;
@@ -509,18 +558,18 @@ var DragManager = class {
   startDrag(e, panel, mode) {
     e.preventDefault();
     e.stopPropagation();
-    const connectedPanels = getConnectedGroup(panel, this.panels);
-    const initialGroupPositions = /* @__PURE__ */ new Map();
-    for (const p of connectedPanels) {
-      const rect2 = p.element.getBoundingClientRect();
-      initialGroupPositions.set(p.id, { x: rect2.left, y: rect2.top });
-    }
     let movingPanels;
     if (mode === "single") {
       detachFromGroup(panel, this.panels);
       movingPanels = [panel];
     } else {
-      movingPanels = connectedPanels;
+      movingPanels = getMovingGroupRespectingPins(panel, this.panels);
+      if (movingPanels.length === 0) return;
+    }
+    const initialGroupPositions = /* @__PURE__ */ new Map();
+    for (const p of movingPanels) {
+      const rect2 = p.element.getBoundingClientRect();
+      initialGroupPositions.set(p.id, { x: rect2.left, y: rect2.top });
     }
     const rect = panel.element.getBoundingClientRect();
     this.activeDrag = {
@@ -1010,6 +1059,7 @@ var AutoHideManager = class {
    */
   handleActivity() {
     for (const panel of this.panels.values()) {
+      if (panel.isPinned) continue;
       if (this.pausedPanels.has(panel.id)) continue;
       if (panel.resolvedAutoHideDelay !== void 0 || panel.isHidden) {
         this.show(panel, "activity");
@@ -1070,9 +1120,27 @@ var AutoHideManager = class {
    */
   hide(panel, trigger) {
     if (panel.isHidden) return;
+    if (panel.isPinned) return;
     hidePanel(panel, this.classes);
     this.callbacks.onHide?.(panel, trigger);
   }
+  /**
+   * Called when a panel's pin state changes.
+   * Pinning cancels the hide timer and reveals the panel if hidden.
+   * Unpinning restarts the timer if the panel participates in auto-hide.
+   */
+  onPanelPinChanged(panel) {
+    if (panel.isPinned) {
+      this.clearTimer(panel.id);
+      if (panel.isHidden) {
+        this.show(panel, "api");
+      }
+    } else {
+      if (!panel.isHidden && panel.resolvedAutoHideDelay !== void 0) {
+        this.scheduleHide(panel);
+      }
+    }
+  }
   /**
    * Initialize a newly added panel's auto-hide state
    */
@@ -1127,6 +1195,7 @@ function generateClasses(prefix) {
     panelContent: `${prefix}-content`,
     panelContentCollapsed: `${prefix}-content-collapsed`,
     detachGrip: `${prefix}-detach-grip`,
+    pinButton: `${prefix}-pin-btn`,
     collapseButton: `${prefix}-collapse-btn`,
     snapPreview: `${prefix}-snap-preview`,
     snapPreviewVisible: `${prefix}-snap-preview-visible`,
@@ -1217,6 +1286,7 @@ var TabManager = class {
       id,
       element,
       dragHandle: options.dragHandle,
+      pinButton: options.pinButton,
       collapseButton: options.collapseButton,
       contentWrapper: options.contentWrapper,
       detachGrip: options.detachGrip,
@@ -1306,15 +1376,25 @@ var TabManager = class {
         this.emit("panel:collapse", { panel: state, isCollapsed: newState });
       });
     }
+    if (state.pinButton) {
+      state.pinButton.addEventListener("click", () => {
+        const isPinned = togglePin(state);
+        this.autoHideManager.onPanelPinChanged(state);
+        this.emit("panel:pin", { panel: state, isPinned });
+      });
+    }
     if (state.detachGrip) {
       state.detachGrip.addEventListener("mousedown", (e) => {
+        if (state.isPinned) return;
         this.dragManager.startDrag(e, state, "single");
       });
     }
     state.dragHandle.addEventListener("mousedown", (e) => {
-      if (e.target === state.collapseButton || e.target === state.detachGrip) {
+      const target = e.target;
+      if (e.target === state.collapseButton || e.target === state.detachGrip || state.pinButton && state.pinButton.contains(target)) {
         return;
       }
+      if (state.isPinned) return;
       this.dragManager.startDrag(e, state, "group");
     });
   }
@@ -1554,6 +1634,80 @@ var TabManager = class {
     this.debugPanelElements.clear();
   }
 };
+
+// src/TagButton.ts
+function createTagButton(label, config = {}) {
+  const { defaultActive = false, inputs = [], onChange } = config;
+  const hasInputs = inputs.length > 0;
+  const el = document.createElement(hasInputs ? "div" : "button");
+  el.className = "blork-tabs-tag-btn";
+  if (hasInputs) {
+    el.setAttribute("role", "button");
+    el.setAttribute("tabindex", "0");
+  }
+  el.appendChild(document.createTextNode(label));
+  const inputElements = [];
+  if (hasInputs) {
+    const inputsContainer = document.createElement("span");
+    inputsContainer.className = "blork-tabs-tag-inputs";
+    for (const inputConfig of inputs) {
+      if (inputConfig.label) {
+        const labelSpan = document.createElement("span");
+        labelSpan.textContent = inputConfig.label;
+        inputsContainer.appendChild(labelSpan);
+      }
+      if (inputConfig.type === "select") {
+        const select = document.createElement("select");
+        select.className = "blork-tabs-tag-select";
+        for (const opt of inputConfig.options ?? []) {
+          const option = document.createElement("option");
+          option.value = opt.value;
+          option.textContent = opt.label;
+          select.appendChild(option);
+        }
+        select.addEventListener("click", (e) => e.stopPropagation());
+        select.addEventListener("mousedown", (e) => e.stopPropagation());
+        inputsContainer.appendChild(select);
+        inputElements.push(select);
+      } else {
+        const input = document.createElement("input");
+        input.type = "number";
+        input.className = "blork-tabs-tag-input";
+        if (inputConfig.defaultValue !== void 0) input.value = String(inputConfig.defaultValue);
+        if (inputConfig.step !== void 0) input.step = String(inputConfig.step);
+        if (inputConfig.min !== void 0) input.min = String(inputConfig.min);
+        if (inputConfig.max !== void 0) input.max = String(inputConfig.max);
+        input.addEventListener("click", (e) => e.stopPropagation());
+        inputsContainer.appendChild(input);
+        inputElements.push(input);
+      }
+    }
+    el.appendChild(inputsContainer);
+  }
+  let active = defaultActive;
+  if (active) el.classList.add("active");
+  const setActive = (value) => {
+    active = value;
+    el.classList.toggle("active", active);
+    onChange?.(active);
+  };
+  el.addEventListener("click", () => setActive(!active));
+  el.addEventListener("keydown", (e) => {
+    const ke = e;
+    if (ke.key === "Enter" || ke.key === " ") {
+      ke.preventDefault();
+      setActive(!active);
+    }
+  });
+  return {
+    element: el,
+    isActive: () => active,
+    setActive,
+    toggle: () => setActive(!active),
+    getValue: (index) => inputElements[index]?.value ?? "",
+    getInput: (index) => inputElements[index]
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AnchorManager,
@@ -1568,6 +1722,7 @@ var TabManager = class {
   createPanelElement,
   createPanelState,
   createPresetAnchor,
+  createTagButton,
   detachFromGroup,
   findSnapTarget,
   getConnectedGroup,
@@ -1575,6 +1730,7 @@ var TabManager = class {
   getDefaultZIndex,
   getDragZIndex,
   getLeftmostPanel,
+  getMovingGroupRespectingPins,
   getPanelDimensions,
   getPanelPosition,
   getRightmostPanel,
@@ -1586,6 +1742,7 @@ var TabManager = class {
   snapPanels,
   snapPanelsToTarget,
   toggleCollapse,
+  togglePin,
   unsnap,
   updateSnappedPositions
 });

package/dist/index.d.cts

@@ -52,6 +52,8 @@ interface PanelConfig {
     title?: string;
     /** Initial width (default: 300) */
     width?: number;
+    /** Initial pin state (default: false) */
+    startPinned?: boolean;
     /** Initial collapsed state (default: true) */
     startCollapsed?: boolean;
     /** Initial position (optional - will be auto-positioned if not provided) */
@@ -65,12 +67,16 @@ interface PanelConfig {
     element?: HTMLDivElement;
     /** Custom drag handle element */
     dragHandle?: HTMLDivElement;
+    /** Custom pin button element */
+    pinButton?: HTMLButtonElement;
     /** Custom collapse button element */
     collapseButton?: HTMLButtonElement;
     /** Custom content wrapper element */
     contentWrapper?: HTMLDivElement;
     /** Custom detach grip element */
     detachGrip?: HTMLDivElement;
+    /** Whether panel can be pinned (default: false) */
+    pinnable?: boolean;
     /** Whether panel can be collapsed (default: true) */
     collapsible?: boolean;
     /** Whether panel can be detached from group (default: true) */
@@ -111,12 +117,16 @@ interface PanelState {
     element: HTMLDivElement;
     /** Drag handle element */
     dragHandle: HTMLDivElement;
+    /** Pin button element (if pinable) */
+    pinButton: HTMLButtonElement | null;
     /** Collapse button element (if collapsible) */
     collapseButton: HTMLButtonElement | null;
     /** Content wrapper element */
     contentWrapper: HTMLDivElement;
     /** Detach grip element (if detachable) */
     detachGrip: HTMLDivElement | null;
+    /** Whether panel is currently pinned */
+    isPinned: boolean;
     /** Whether panel is currently collapsed */
     isCollapsed: boolean;
     /** ID of panel this is snapped to on its right (outgoing link) */
@@ -226,6 +236,8 @@ interface TabManagerEvents {
     'snap:anchor': AnchorSnapEvent;
     /** Fired when a panel is detached from group */
     'panel:detached': PanelDetachedEvent;
+    /** Fired when panel pin state changes */
+    'panel:pin': PanelPinEvent;
     /** Fired when panel collapse state changes */
     'panel:collapse': PanelCollapseEvent;
     /** Fired when a panel becomes visible (auto-hide) */
@@ -269,6 +281,10 @@ interface PanelDetachedEvent {
     panel: PanelState;
     previousGroup: PanelState[];
 }
+interface PanelPinEvent {
+    panel: PanelState;
+    isPinned: boolean;
+}
 interface PanelCollapseEvent {
     panel: PanelState;
     isCollapsed: boolean;
@@ -295,6 +311,7 @@ interface CSSClasses {
     panelContent: string;
     panelContentCollapsed: string;
     detachGrip: string;
+    pinButton: string;
     collapseButton: string;
     snapPreview: string;
     snapPreviewVisible: string;
@@ -403,6 +420,7 @@ declare class TabManager {
      */
     registerPanel(id: string, element: HTMLDivElement, options?: {
         dragHandle?: HTMLDivElement;
+        pinButton?: HTMLButtonElement;
         collapseButton?: HTMLButtonElement;
         contentWrapper?: HTMLDivElement;
         detachGrip?: HTMLDivElement;
@@ -734,6 +752,12 @@ declare class AutoHideManager {
      * Hide a panel
      */
     hide(panel: PanelState, trigger: 'timeout' | 'api'): void;
+    /**
+     * Called when a panel's pin state changes.
+     * Pinning cancels the hide timer and reveals the panel if hidden.
+     * Unpinning restarts the timer if the panel participates in auto-hide.
+     */
+    onPanelPinChanged(panel: PanelState): void;
     /**
      * Initialize a newly added panel's auto-hide state
      */
@@ -799,6 +823,67 @@ interface HoverEnlargeConfig {
  */
 declare function setupHoverEnlarge(config: HoverEnlargeConfig): void;
 
+/**
+ * Tag button: a toggleable pill-shaped button that optionally reveals
+ * inline inputs (numbers, selects) when active.
+ *
+ * @example
+ * ```typescript
+ * // Simple toggle
+ * const staticBtn = createTagButton('static');
+ * container.appendChild(staticBtn.element);
+ *
+ * // Toggle with parameterized inputs
+ * const govBtn = createTagButton('gravity_override', {
+ *   inputs: [
+ *     { label: 'x', defaultValue: 0, step: 0.1 },
+ *     { label: 'y', defaultValue: -1, step: 0.1 },
+ *   ],
+ * });
+ * container.appendChild(govBtn.element);
+ *
+ * // Read state when needed
+ * if (govBtn.isActive()) {
+ *   const gx = parseFloat(govBtn.getValue(0));
+ *   const gy = parseFloat(govBtn.getValue(1));
+ * }
+ * ```
+ */
+interface TagButtonNumberInputConfig {
+    type?: 'number';
+    /** Short label rendered before the input (e.g. 'x', 'y') */
+    label?: string;
+    defaultValue?: number;
+    step?: number;
+    min?: number;
+    max?: number;
+}
+interface TagButtonSelectInputConfig {
+    type: 'select';
+    label?: string;
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+}
+type TagButtonInputConfig = TagButtonNumberInputConfig | TagButtonSelectInputConfig;
+interface TagButtonConfig {
+    defaultActive?: boolean;
+    inputs?: TagButtonInputConfig[];
+    onChange?: (active: boolean) => void;
+}
+interface TagButton {
+    element: HTMLElement;
+    isActive(): boolean;
+    setActive(active: boolean): void;
+    toggle(): void;
+    /** Get the string value of the input at position index */
+    getValue(index: number): string;
+    /** Direct access to the underlying input or select element */
+    getInput(index: number): HTMLInputElement | HTMLSelectElement | undefined;
+}
+declare function createTagButton(label: string, config?: TagButtonConfig): TagButton;
+
 /**
  * @blorkfield/blork-tabs - Panel
  * Individual panel component with collapse/expand functionality
@@ -810,6 +895,7 @@ declare function setupHoverEnlarge(config: HoverEnlargeConfig): void;
 declare function createPanelElement(config: PanelConfig, classes: CSSClasses): {
     element: HTMLDivElement;
     dragHandle: HTMLDivElement;
+    pinButton: HTMLButtonElement | null;
     collapseButton: HTMLButtonElement | null;
     contentWrapper: HTMLDivElement;
     detachGrip: HTMLDivElement | null;
@@ -825,6 +911,10 @@ declare function createPanelState(config: PanelConfig, classes: CSSClasses, glob
  * Toggle panel collapse state
  */
 declare function toggleCollapse(state: PanelState, classes: CSSClasses, collapsed?: boolean): boolean;
+/**
+ * Toggle panel pin state
+ */
+declare function togglePin(state: PanelState, pinned?: boolean): boolean;
 /**
  * Show a hidden panel
  */
@@ -909,9 +999,21 @@ declare function areInSameChain(panel1: PanelState, panel2: PanelState, panels:
  * Establish a snap relationship between two panels
  */
 declare function snapPanels(leftPanel: PanelState, rightPanel: PanelState): void;
+/**
+ * Get the subset of connected panels that should move when a panel is grabbed,
+ * stopping at any pinned panel in the chain.
+ *
+ * Pinned panels act as immoveable barriers — the chain splits at each one,
+ * and only the panels on the same side as the grabbed panel are returned.
+ * The snap bonds at each pin boundary are severed as a side effect.
+ *
+ * Example: chain [A, B, P(pinned), C, D], grab B → returns [A, B], unseats B↔P
+ * Example: chain [A, P(pinned), B, C], grab C → returns [B, C], unseats P↔B
+ */
+declare function getMovingGroupRespectingPins(grabbedPanel: PanelState, panels: Map<string, PanelState>): PanelState[];
 /**
  * Break the snap relationship between two specific panels
  */
 declare function unsnap(leftPanel: PanelState, rightPanel: PanelState): void;
 
-export { type AnchorConfig, AnchorManager, type AnchorPreset, type AnchorSnapEvent, type AnchorSnapResult, type AnchorState, type AutoHideCallbacks, AutoHideManager, type Bounds, type CSSClasses, type DebugLog, type DebugLogConfig, type DebugLogLevel, type DebugPanel, type DebugPanelConfig, type DragEndEvent, DragManager, type DragMode, type DragMoveEvent, type DragStartEvent, type DragState, type EventListener, type PanelAddedEvent, type PanelCollapseEvent, type PanelConfig, type PanelDetachedEvent, type PanelHideEvent, type PanelRemovedEvent, type PanelShowEvent, type PanelSnapEvent, type PanelState, type Position, type ResolvedTabManagerConfig, SnapPreview, type SnapSide, type SnapTarget, TabManager, type TabManagerConfig, type TabManagerEvents, areInSameChain, createDebugLog, createDebugPanelContent, createDebugPanelInterface, createPanelElement, createPanelState, createPresetAnchor, detachFromGroup, findSnapTarget, getConnectedGroup, getDefaultAnchorConfigs, getDefaultZIndex, getDragZIndex, getLeftmostPanel, getPanelDimensions, getPanelPosition, getRightmostPanel, hidePanel, setPanelPosition, setPanelZIndex, setupHoverEnlarge, showPanel, snapPanels, snapPanelsToTarget, toggleCollapse, unsnap, updateSnappedPositions };
+export { type AnchorConfig, AnchorManager, type AnchorPreset, type AnchorSnapEvent, type AnchorSnapResult, type AnchorState, type AutoHideCallbacks, AutoHideManager, type Bounds, type CSSClasses, type DebugLog, type DebugLogConfig, type DebugLogLevel, type DebugPanel, type DebugPanelConfig, type DragEndEvent, DragManager, type DragMode, type DragMoveEvent, type DragStartEvent, type DragState, type EventListener, type PanelAddedEvent, type PanelCollapseEvent, type PanelConfig, type PanelDetachedEvent, type PanelHideEvent, type PanelPinEvent, type PanelRemovedEvent, type PanelShowEvent, type PanelSnapEvent, type PanelState, type Position, type ResolvedTabManagerConfig, SnapPreview, type SnapSide, type SnapTarget, TabManager, type TabManagerConfig, type TabManagerEvents, type TagButton, type TagButtonConfig, type TagButtonInputConfig, type TagButtonNumberInputConfig, type TagButtonSelectInputConfig, areInSameChain, createDebugLog, createDebugPanelContent, createDebugPanelInterface, createPanelElement, createPanelState, createPresetAnchor, createTagButton, detachFromGroup, findSnapTarget, getConnectedGroup, getDefaultAnchorConfigs, getDefaultZIndex, getDragZIndex, getLeftmostPanel, getMovingGroupRespectingPins, getPanelDimensions, getPanelPosition, getRightmostPanel, hidePanel, setPanelPosition, setPanelZIndex, setupHoverEnlarge, showPanel, snapPanels, snapPanelsToTarget, toggleCollapse, togglePin, unsnap, updateSnappedPositions };