@blorkfield/blork-tabs 0.1.3

package/dist/index.d.ts

@@ -0,0 +1,669 @@
+/**
+ * @blorkfield/blork-tabs - Type Definitions
+ * A framework-agnostic tab/panel management system with snapping and docking
+ */
+/**
+ * Configuration for initializing the TabManager
+ */
+interface TabManagerConfig {
+    /** Distance threshold for panel-to-panel snapping (default: 50) */
+    snapThreshold?: number;
+    /** Gap between snapped panels (default: 0) */
+    panelGap?: number;
+    /** Margin from window edges (default: 16) */
+    panelMargin?: number;
+    /** Distance threshold for anchor snapping (default: 80) */
+    anchorThreshold?: number;
+    /** Default panel width for anchor calculations (default: 300) */
+    defaultPanelWidth?: number;
+    /** Container element for panels (default: document.body) */
+    container?: HTMLElement;
+    /** Whether to automatically initialize default anchors (default: true) */
+    initializeDefaultAnchors?: boolean;
+    /** Custom CSS class prefix (default: 'blork-tabs') */
+    classPrefix?: string;
+}
+/**
+ * Resolved configuration with all defaults applied
+ */
+interface ResolvedTabManagerConfig {
+    snapThreshold: number;
+    panelGap: number;
+    panelMargin: number;
+    anchorThreshold: number;
+    defaultPanelWidth: number;
+    container: HTMLElement;
+    initializeDefaultAnchors: boolean;
+    classPrefix: string;
+}
+/**
+ * Configuration for creating a new panel
+ */
+interface PanelConfig {
+    /** Unique identifier for the panel */
+    id: string;
+    /** Panel title displayed in header */
+    title?: string;
+    /** Initial width (default: 300) */
+    width?: number;
+    /** Initial collapsed state (default: true) */
+    startCollapsed?: boolean;
+    /** Initial position (optional - will be auto-positioned if not provided) */
+    initialPosition?: {
+        x: number;
+        y: number;
+    };
+    /** Content element or HTML string */
+    content?: HTMLElement | string;
+    /** Custom panel element (for existing DOM panels) */
+    element?: HTMLDivElement;
+    /** Custom drag handle element */
+    dragHandle?: HTMLDivElement;
+    /** Custom collapse button element */
+    collapseButton?: HTMLButtonElement;
+    /** Custom content wrapper element */
+    contentWrapper?: HTMLDivElement;
+    /** Custom detach grip element */
+    detachGrip?: HTMLDivElement;
+    /** Whether panel can be collapsed (default: true) */
+    collapsible?: boolean;
+    /** Whether panel can be detached from group (default: true) */
+    detachable?: boolean;
+    /** Whether panel can be dragged (default: true) */
+    draggable?: boolean;
+    /** Z-index for panel (default: 1000) */
+    zIndex?: number;
+    /** Z-index when dragging (default: 1002) */
+    dragZIndex?: number;
+}
+/**
+ * Configuration for anchor points
+ */
+interface AnchorConfig {
+    /** Unique identifier for the anchor */
+    id: string;
+    /** Function that returns the anchor position (allows dynamic positioning) */
+    getPosition: () => Position;
+    /** Whether to show visual indicator (default: true) */
+    showIndicator?: boolean;
+}
+/**
+ * Preset anchor positions
+ */
+type AnchorPreset = 'top-left' | 'top-right' | 'top-center' | 'bottom-left' | 'bottom-right' | 'bottom-center' | 'center-left' | 'center-right';
+/**
+ * Current state of a panel
+ */
+interface PanelState {
+    /** Unique panel identifier */
+    id: string;
+    /** DOM element for the panel */
+    element: HTMLDivElement;
+    /** Drag handle element */
+    dragHandle: HTMLDivElement;
+    /** 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 collapsed */
+    isCollapsed: boolean;
+    /** ID of panel this is snapped to on its right (outgoing link) */
+    snappedTo: string | null;
+    /** ID of panel snapped to this on its left (incoming link) */
+    snappedFrom: string | null;
+    /** Panel configuration */
+    config: PanelConfig;
+}
+/**
+ * Current drag operation state
+ */
+interface DragState {
+    /** Panel that initiated the drag */
+    grabbedPanel: PanelState;
+    /** Mouse offset from panel left edge */
+    offsetX: number;
+    /** Mouse offset from panel top edge */
+    offsetY: number;
+    /** Initial positions of all connected panels */
+    initialGroupPositions: Map<string, Position>;
+    /** Panels being moved in this drag operation */
+    movingPanels: PanelState[];
+    /** Drag mode - single panel or entire group */
+    mode: DragMode;
+}
+/**
+ * Drag mode determines what gets moved
+ */
+type DragMode = 'single' | 'group';
+/**
+ * Anchor state including visual indicator
+ */
+interface AnchorState {
+    /** Anchor configuration */
+    config: AnchorConfig;
+    /** Visual indicator element */
+    indicator: HTMLDivElement | null;
+}
+/**
+ * Result of snap target detection
+ */
+interface SnapTarget {
+    /** ID of the target panel */
+    targetId: string;
+    /** Which side of target to snap to */
+    side: SnapSide;
+    /** X position for snap */
+    x: number;
+    /** Y position for snap */
+    y: number;
+}
+/**
+ * Side of panel to snap to
+ */
+type SnapSide = 'left' | 'right';
+/**
+ * Result of anchor snap detection
+ */
+interface AnchorSnapResult {
+    /** The matched anchor */
+    anchor: AnchorState;
+    /** Index of panel in group that docks to anchor */
+    dockPanelIndex: number;
+    /** Final positions for all panels in the group */
+    positions: Position[];
+}
+/**
+ * Simple x,y position
+ */
+interface Position {
+    x: number;
+    y: number;
+}
+/**
+ * Bounding rectangle
+ */
+interface Bounds {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    width: number;
+    height: number;
+}
+/**
+ * Events emitted by TabManager
+ */
+interface TabManagerEvents {
+    /** Fired when a panel is added */
+    'panel:added': PanelAddedEvent;
+    /** Fired when a panel is removed */
+    'panel:removed': PanelRemovedEvent;
+    /** Fired when a panel starts being dragged */
+    'drag:start': DragStartEvent;
+    /** Fired during drag movement */
+    'drag:move': DragMoveEvent;
+    /** Fired when drag ends */
+    'drag:end': DragEndEvent;
+    /** Fired when panels snap together */
+    'snap:panel': PanelSnapEvent;
+    /** Fired when panels snap to anchor */
+    'snap:anchor': AnchorSnapEvent;
+    /** Fired when a panel is detached from group */
+    'panel:detached': PanelDetachedEvent;
+    /** Fired when panel collapse state changes */
+    'panel:collapse': PanelCollapseEvent;
+}
+interface PanelAddedEvent {
+    panel: PanelState;
+}
+interface PanelRemovedEvent {
+    panelId: string;
+}
+interface DragStartEvent {
+    panel: PanelState;
+    mode: DragMode;
+    movingPanels: PanelState[];
+}
+interface DragMoveEvent {
+    panel: PanelState;
+    position: Position;
+    snapTarget: SnapTarget | null;
+    anchorTarget: AnchorSnapResult | null;
+}
+interface DragEndEvent {
+    panel: PanelState;
+    finalPosition: Position;
+    snappedToPanel: boolean;
+    snappedToAnchor: boolean;
+}
+interface PanelSnapEvent {
+    movingPanels: PanelState[];
+    targetPanel: PanelState;
+    side: SnapSide;
+}
+interface AnchorSnapEvent {
+    movingPanels: PanelState[];
+    anchor: AnchorState;
+}
+interface PanelDetachedEvent {
+    panel: PanelState;
+    previousGroup: PanelState[];
+}
+interface PanelCollapseEvent {
+    panel: PanelState;
+    isCollapsed: boolean;
+}
+/**
+ * Event listener function type
+ */
+type EventListener<T> = (event: T) => void;
+/**
+ * CSS class names used by the library
+ */
+interface CSSClasses {
+    panel: string;
+    panelHeader: string;
+    panelTitle: string;
+    panelContent: string;
+    panelContentCollapsed: string;
+    detachGrip: string;
+    collapseButton: string;
+    snapPreview: string;
+    snapPreviewVisible: string;
+    anchorIndicator: string;
+    anchorIndicatorVisible: string;
+    anchorIndicatorActive: string;
+    dragging: string;
+}
+
+/**
+ * @blorkfield/blork-tabs - TabManager
+ * Main orchestrator for the tab/panel management system
+ */
+
+/**
+ * Main TabManager class - orchestrates all panel, snap, and anchor functionality
+ */
+declare class TabManager {
+    private config;
+    private classes;
+    private panels;
+    private dragManager;
+    private anchorManager;
+    private snapPreview;
+    private eventListeners;
+    constructor(userConfig?: TabManagerConfig);
+    /**
+     * Add a new panel
+     */
+    addPanel(panelConfig: PanelConfig): PanelState;
+    /**
+     * Register an existing panel element
+     */
+    registerPanel(id: string, element: HTMLDivElement, options?: {
+        dragHandle?: HTMLDivElement;
+        collapseButton?: HTMLButtonElement;
+        contentWrapper?: HTMLDivElement;
+        detachGrip?: HTMLDivElement;
+        startCollapsed?: boolean;
+    }): PanelState;
+    /**
+     * Remove a panel
+     */
+    removePanel(id: string): boolean;
+    /**
+     * Get a panel by ID
+     */
+    getPanel(id: string): PanelState | undefined;
+    /**
+     * Get all panels
+     */
+    getAllPanels(): PanelState[];
+    /**
+     * Set up event handlers for a panel
+     */
+    private setupPanelEvents;
+    /**
+     * Get all panels in the same snap chain as the given panel
+     */
+    getSnapChain(panelId: string): PanelState[];
+    /**
+     * Manually snap two panels together
+     */
+    snap(leftPanelId: string, rightPanelId: string): boolean;
+    /**
+     * Detach a panel from its snap chain
+     */
+    detach(panelId: string): boolean;
+    /**
+     * Update snapped positions (call after collapse/expand or resize)
+     */
+    updatePositions(): void;
+    /**
+     * Add a custom anchor
+     */
+    addAnchor(config: AnchorConfig): AnchorState;
+    /**
+     * Add a preset anchor
+     */
+    addPresetAnchor(preset: AnchorPreset): AnchorState;
+    /**
+     * Remove an anchor
+     */
+    removeAnchor(id: string): boolean;
+    /**
+     * Get all anchors
+     */
+    getAnchors(): AnchorState[];
+    private handleDragStart;
+    private handleDragMove;
+    private handleDragEnd;
+    /**
+     * Subscribe to an event
+     */
+    on<K extends keyof TabManagerEvents>(event: K, listener: EventListener<TabManagerEvents[K]>): () => void;
+    /**
+     * Unsubscribe from an event
+     */
+    off<K extends keyof TabManagerEvents>(event: K, listener: EventListener<TabManagerEvents[K]>): void;
+    /**
+     * Emit an event
+     */
+    private emit;
+    /**
+     * Position panels in a row from right edge
+     */
+    positionPanelsFromRight(panelIds: string[], gap?: number): void;
+    /**
+     * Position panels in a row from left edge
+     */
+    positionPanelsFromLeft(panelIds: string[], gap?: number): void;
+    /**
+     * Set up initial snap chain for a list of panels (left to right)
+     */
+    createSnapChain(panelIds: string[]): void;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): ResolvedTabManagerConfig;
+    /**
+     * Get the CSS classes used
+     */
+    getClasses(): CSSClasses;
+    /**
+     * Check if dragging is currently active
+     */
+    isDragging(): boolean;
+    /**
+     * Destroy the TabManager and clean up resources
+     */
+    destroy(): void;
+}
+
+/**
+ * @blorkfield/blork-tabs - AnchorManager
+ * Manages screen anchor points for panel docking
+ */
+
+/**
+ * Creates the default anchor positions
+ */
+declare function getDefaultAnchorConfigs(config: ResolvedTabManagerConfig): AnchorConfig[];
+/**
+ * Create an anchor preset config
+ */
+declare function createPresetAnchor(preset: AnchorPreset, config: ResolvedTabManagerConfig): AnchorConfig;
+/**
+ * Manages anchor points and docking behavior
+ */
+declare class AnchorManager {
+    private anchors;
+    private config;
+    private classes;
+    private container;
+    constructor(config: ResolvedTabManagerConfig, classes: CSSClasses);
+    /**
+     * Create an anchor indicator element
+     */
+    private createIndicator;
+    /**
+     * Add an anchor point
+     */
+    addAnchor(anchorConfig: AnchorConfig): AnchorState;
+    /**
+     * Add multiple default anchors
+     */
+    addDefaultAnchors(): void;
+    /**
+     * Add anchor from preset
+     */
+    addPresetAnchor(preset: AnchorPreset): AnchorState;
+    /**
+     * Remove an anchor
+     */
+    removeAnchor(id: string): boolean;
+    /**
+     * Update position of a single indicator
+     */
+    private updateIndicatorPosition;
+    /**
+     * Update all indicator positions (call on window resize)
+     */
+    updateIndicatorPositions(): void;
+    /**
+     * Find the nearest anchor for a group of moving panels
+     */
+    findNearestAnchor(movingPanels: PanelState[]): AnchorSnapResult | null;
+    /**
+     * Show anchor indicators during drag
+     */
+    showIndicators(activeAnchor: AnchorState | null): void;
+    /**
+     * Hide all anchor indicators
+     */
+    hideIndicators(): void;
+    /**
+     * Get all anchors
+     */
+    getAnchors(): AnchorState[];
+    /**
+     * Get anchor by ID
+     */
+    getAnchor(id: string): AnchorState | undefined;
+    /**
+     * Clean up
+     */
+    destroy(): void;
+}
+
+/**
+ * @blorkfield/blork-tabs - DragManager
+ * Handles drag operations for panels including single and group modes
+ */
+
+interface DragCallbacks {
+    onDragStart?: (state: DragState) => void;
+    onDragMove?: (state: DragState, position: Position, snapTarget: SnapTarget | null, anchorResult: AnchorSnapResult | null) => void;
+    onDragEnd?: (state: DragState, snapTarget: SnapTarget | null, anchorResult: AnchorSnapResult | null) => void;
+    findAnchorTarget?: (movingPanels: PanelState[]) => AnchorSnapResult | null;
+}
+/**
+ * Creates and manages drag operations
+ */
+declare class DragManager {
+    private panels;
+    private config;
+    private callbacks;
+    private activeDrag;
+    private boundMouseMove;
+    private boundMouseUp;
+    constructor(panels: Map<string, PanelState>, config: ResolvedTabManagerConfig, callbacks: DragCallbacks);
+    /**
+     * Start a drag operation
+     */
+    startDrag(e: MouseEvent, panel: PanelState, mode: DragMode): void;
+    /**
+     * Handle mouse movement during drag
+     */
+    private handleMouseMove;
+    /**
+     * Handle mouse up - finalize drag
+     */
+    private handleMouseUp;
+    /**
+     * Check if a drag is currently in progress
+     */
+    isActive(): boolean;
+    /**
+     * Get the current drag state
+     */
+    getState(): DragState | null;
+    /**
+     * Clean up event listeners
+     */
+    destroy(): void;
+}
+
+/**
+ * @blorkfield/blork-tabs - SnapPreview
+ * Visual feedback for snap targets during drag operations
+ */
+
+/**
+ * Manages the visual snap preview indicator
+ */
+declare class SnapPreview {
+    private element;
+    private classes;
+    private container;
+    private panels;
+    constructor(container: HTMLElement, classes: CSSClasses, panels: Map<string, PanelState>);
+    /**
+     * Create the preview element lazily
+     */
+    private ensureElement;
+    /**
+     * Update the preview to show a snap target
+     */
+    show(snapTarget: SnapTarget): void;
+    /**
+     * Hide the preview
+     */
+    hide(): void;
+    /**
+     * Update based on current snap target (convenience method)
+     */
+    update(snapTarget: SnapTarget | null): void;
+    /**
+     * Clean up
+     */
+    destroy(): void;
+}
+
+/**
+ * @blorkfield/blork-tabs - Panel
+ * Individual panel component with collapse/expand functionality
+ */
+
+/**
+ * Creates the default panel DOM structure
+ */
+declare function createPanelElement(config: PanelConfig, classes: CSSClasses): {
+    element: HTMLDivElement;
+    dragHandle: HTMLDivElement;
+    collapseButton: HTMLButtonElement | null;
+    contentWrapper: HTMLDivElement;
+    detachGrip: HTMLDivElement | null;
+};
+/**
+ * Creates a PanelState from config, using existing elements or creating new ones
+ */
+declare function createPanelState(config: PanelConfig, classes: CSSClasses): PanelState;
+/**
+ * Toggle panel collapse state
+ */
+declare function toggleCollapse(state: PanelState, classes: CSSClasses, collapsed?: boolean): boolean;
+/**
+ * Set panel position
+ */
+declare function setPanelPosition(state: PanelState, x: number, y: number): void;
+/**
+ * Get panel position from DOM
+ */
+declare function getPanelPosition(state: PanelState): {
+    x: number;
+    y: number;
+};
+/**
+ * Get panel dimensions
+ */
+declare function getPanelDimensions(state: PanelState): {
+    width: number;
+    height: number;
+};
+/**
+ * Set panel z-index
+ */
+declare function setPanelZIndex(state: PanelState, zIndex: number): void;
+/**
+ * Get default z-index for panel
+ */
+declare function getDefaultZIndex(state: PanelState): number;
+/**
+ * Get drag z-index for panel
+ */
+declare function getDragZIndex(state: PanelState): number;
+
+/**
+ * @blorkfield/blork-tabs - SnapChain
+ * Manages snap relationships between panels forming linked chains
+ */
+
+/**
+ * Get all panels connected to a given panel (the entire snap chain)
+ * Returns panels ordered from left to right
+ */
+declare function getConnectedGroup(startPanel: PanelState, panels: Map<string, PanelState>): PanelState[];
+/**
+ * Detach a panel from its snap chain
+ * Clears both incoming and outgoing snap relationships
+ */
+declare function detachFromGroup(panel: PanelState, panels: Map<string, PanelState>): void;
+/**
+ * Find a snap target for the moving panels
+ * Checks if moving panels are close enough to snap to a stationary panel
+ */
+declare function findSnapTarget(movingPanels: PanelState[], panels: Map<string, PanelState>, config: ResolvedTabManagerConfig): SnapTarget | null;
+/**
+ * Execute a snap operation - position panels and establish relationships
+ */
+declare function snapPanelsToTarget(movingPanels: PanelState[], targetId: string, side: SnapSide, x: number, y: number, panels: Map<string, PanelState>, config: ResolvedTabManagerConfig): void;
+/**
+ * Update positions of all snapped panels when one changes size
+ * Traverses from rightmost panel leftward, repositioning as needed
+ */
+declare function updateSnappedPositions(panels: Map<string, PanelState>, config: ResolvedTabManagerConfig): void;
+/**
+ * Get the leftmost panel in a chain
+ */
+declare function getLeftmostPanel(panel: PanelState, panels: Map<string, PanelState>): PanelState;
+/**
+ * Get the rightmost panel in a chain
+ */
+declare function getRightmostPanel(panel: PanelState, panels: Map<string, PanelState>): PanelState;
+/**
+ * Check if two panels are in the same snap chain
+ */
+declare function areInSameChain(panel1: PanelState, panel2: PanelState, panels: Map<string, PanelState>): boolean;
+/**
+ * Establish a snap relationship between two panels
+ */
+declare function snapPanels(leftPanel: PanelState, rightPanel: PanelState): void;
+/**
+ * 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 Bounds, type CSSClasses, type DragEndEvent, DragManager, type DragMode, type DragMoveEvent, type DragStartEvent, type DragState, type EventListener, type PanelAddedEvent, type PanelCollapseEvent, type PanelConfig, type PanelDetachedEvent, type PanelRemovedEvent, type PanelSnapEvent, type PanelState, type Position, type ResolvedTabManagerConfig, SnapPreview, type SnapSide, type SnapTarget, TabManager, type TabManagerConfig, type TabManagerEvents, areInSameChain, createPanelElement, createPanelState, createPresetAnchor, detachFromGroup, findSnapTarget, getConnectedGroup, getDefaultAnchorConfigs, getDefaultZIndex, getDragZIndex, getLeftmostPanel, getPanelDimensions, getPanelPosition, getRightmostPanel, setPanelPosition, setPanelZIndex, snapPanels, snapPanelsToTarget, toggleCollapse, unsnap, updateSnappedPositions };