@principal-ade/panel-layouts 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,580 @@
+import { AnimatedResizableLayout } from '@a24z/panels';
+import { AnimatedResizableLayoutProps } from '@a24z/panels';
+import { AnimatedVerticalLayout } from '@a24z/panels';
+import { AnimatedVerticalLayoutProps } from '@a24z/panels';
+import { AnimationConfig } from '@a24z/panels';
+import { CollapseButtonConfig } from '@a24z/panels';
+import { CollapsibleSide } from '@a24z/panels';
+import { ConfigurablePanelLayout } from '@a24z/panels';
+import { ConfigurablePanelLayoutProps } from '@a24z/panels';
+import { mapThemeToPanelVars } from '@a24z/panels';
+import { mapThemeToTabVars } from '@a24z/panels';
+import { PanelCallbacks } from '@a24z/panels';
+import { PanelConfigurator } from '@a24z/panels';
+import { PanelConfiguratorProps } from '@a24z/panels';
+import { PanelDefinition } from '@a24z/panels';
+import { PanelDefinitionWithContent } from '@a24z/panels';
+import { PanelGroup } from '@a24z/panels';
+import { PanelLayout } from '@a24z/panels';
+import { PanelOrientation } from '@a24z/panels';
+import { PanelSlot } from '@a24z/panels';
+import { SnapCarousel } from '@a24z/panels';
+import { SnapCarouselProps } from '@a24z/panels';
+import { SnapCarouselRef } from '@a24z/panels';
+import { TabGroup } from '@a24z/panels';
+import { TabGroupProps } from '@a24z/panels';
+import { TabsConfig } from '@a24z/panels';
+import { Theme } from '@a24z/panels';
+import { ThemeMode } from '@a24z/panels';
+import { ThreePanelLayout } from '@a24z/panels';
+import { ThreePanelLayoutProps } from '@a24z/panels';
+import { TilesConfig } from '@a24z/panels';
+import { useLocalStorage } from '@a24z/panels';
+import { useMediaQuery } from '@a24z/panels';
+
+export { AnimatedResizableLayout }
+
+export { AnimatedResizableLayoutProps }
+
+export { AnimatedVerticalLayout }
+
+export { AnimatedVerticalLayoutProps }
+
+export { AnimationConfig }
+
+/**
+ * Built-in workspace IDs
+ */
+export declare type BuiltInWorkspaceId = 'project-management' | 'code-review' | 'documentation' | 'agent-work' | 'quality-check' | 'drawing' | 'old-school' | 'principal-office';
+
+export { CollapseButtonConfig }
+
+export { CollapsibleSide }
+
+export { ConfigurablePanelLayout }
+
+export { ConfigurablePanelLayoutProps }
+
+/**
+ * Options for creating a new workspace
+ */
+export declare interface CreateWorkspaceOptions {
+    name: string;
+    layout: PanelLayout;
+    description?: string;
+    defaultSizes?: {
+        left: number;
+        middle: number;
+        right: number;
+    };
+    defaultCollapsed?: {
+        left?: boolean;
+        right?: boolean;
+    };
+}
+
+/**
+ * Default localStorage-based persistence adapter for web applications
+ */
+export declare class LocalStoragePersistenceAdapter implements PersistenceAdapter {
+    private storageKey;
+    load(viewKey: string): Promise<any>;
+    save(viewKey: string, state: {
+        sizes: PanelSizes | TwoPanelSizes;
+    }): Promise<void>;
+}
+
+export declare class LocalStorageWorkspaceAdapter implements WorkspaceStorageAdapter {
+    private readonly PRESETS_KEY;
+    private readonly REPO_STATE_PREFIX;
+    /**
+     * Load all user-created workspace presets
+     */
+    loadWorkspacePresets(): Promise<Record<string, WorkspaceLayout>>;
+    /**
+     * Save workspace presets
+     */
+    saveWorkspacePresets(presets: Record<string, WorkspaceLayout>): Promise<void>;
+    /**
+     * Load repository-specific workspace state
+     */
+    loadRepositoryState(repositoryKey: string): Promise<RepositoryWorkspaceState | null>;
+    /**
+     * Save repository-specific workspace state
+     */
+    saveRepositoryState(repositoryKey: string, state: RepositoryWorkspaceState): Promise<void>;
+    /**
+     * Load all repository states
+     */
+    loadAllRepositoryStates(): Promise<Record<string, RepositoryWorkspaceState>>;
+}
+
+export { mapThemeToPanelVars }
+
+export { mapThemeToTabVars }
+
+export { PanelCallbacks }
+
+/**
+ * Collapsed state for panels
+ */
+export declare interface PanelCollapsed {
+    left?: boolean;
+    right?: boolean;
+}
+
+export { PanelConfigurator }
+
+export { PanelConfiguratorProps }
+
+export { PanelDefinition }
+
+export { PanelDefinitionWithContent }
+
+export { PanelGroup }
+
+export { PanelLayout }
+
+export { PanelOrientation }
+
+/**
+ * Union type for panel persistence return types
+ */
+export declare type PanelPersistence = ThreePanelPersistence | TwoPanelPersistence;
+
+/**
+ * Persistence type definitions
+ * These types define how panel layouts are persisted and restored
+ */
+/**
+ * Panel sizes for a three-panel layout
+ */
+export declare interface PanelSizes {
+    left: number;
+    middle: number;
+    right: number;
+}
+
+export { PanelSlot }
+
+/**
+ * Storage adapter interface for persisting panel state
+ * Implementations can use localStorage, Electron IPC, or remote storage
+ */
+export declare interface PersistenceAdapter {
+    /** Load saved panel layout state for a given view */
+    load(viewKey: string): Promise<{
+        sizes?: PanelSizes | TwoPanelSizes;
+        collapsed?: PanelCollapsed | {
+            left?: boolean;
+        };
+    } | null>;
+    /** Save panel layout state for a given view */
+    save(viewKey: string, state: {
+        sizes: PanelSizes | TwoPanelSizes;
+        collapsed?: PanelCollapsed | {
+            left?: boolean;
+        };
+    }): Promise<void>;
+}
+
+/**
+ * Repository-specific workspace state
+ * Tracks which workspace is active and current panel configuration for a repository
+ */
+export declare interface RepositoryWorkspaceState {
+    /** ID of the active workspace, or null for custom layout */
+    workspaceId: string | null;
+    /** Custom layout (only used when workspaceId is null) */
+    layout?: PanelLayout;
+    /** Current panel sizes */
+    sizes: {
+        left: number;
+        middle: number;
+        right: number;
+    };
+    /** Current collapsed state */
+    collapsed: {
+        left?: boolean;
+        right?: boolean;
+    };
+    /** Active panels in each section (for tab groups) */
+    activePanels?: {
+        left?: string;
+        middle?: string;
+        right?: string;
+    };
+}
+
+export { SnapCarousel }
+
+export { SnapCarouselProps }
+
+export { SnapCarouselRef }
+
+export { TabGroup }
+
+export { TabGroupProps }
+
+export { TabsConfig }
+
+export { Theme }
+
+export { ThemeMode }
+
+export { ThreePanelLayout }
+
+export { ThreePanelLayoutProps }
+
+/**
+ * Return type for the usePanelPersistence hook (three-panel variant)
+ */
+export declare interface ThreePanelPersistence {
+    type: 'three-panel';
+    sizes: PanelSizes;
+    collapsed: PanelCollapsed;
+    handlePanelResize: (sizes: PanelSizes) => void;
+    handleLeftCollapseComplete: () => Promise<void>;
+    handleLeftExpandComplete: () => Promise<void>;
+    handleRightCollapseComplete: () => Promise<void>;
+    handleRightExpandComplete: () => Promise<void>;
+}
+
+export { TilesConfig }
+
+/**
+ * Return type for the usePanelPersistence hook (two-panel variant)
+ */
+export declare interface TwoPanelPersistence {
+    type: 'two-panel';
+    sizes: TwoPanelSizes;
+    collapsed: {
+        left?: boolean;
+    };
+    handlePanelResize: (sizes: TwoPanelSizes) => void;
+    handleLeftCollapseComplete: () => Promise<void>;
+    handleLeftExpandComplete: () => Promise<void>;
+}
+
+/**
+ * Panel sizes for a two-panel layout
+ */
+export declare interface TwoPanelSizes {
+    left: number;
+    right: number;
+}
+
+/**
+ * Options for updating an existing workspace
+ */
+export declare interface UpdateWorkspaceOptions {
+    name?: string;
+    description?: string;
+    layout?: PanelLayout;
+    defaultSizes?: {
+        left: number;
+        middle: number;
+        right: number;
+    };
+    defaultCollapsed?: {
+        left?: boolean;
+        right?: boolean;
+    };
+}
+
+export { useLocalStorage }
+
+export { useMediaQuery }
+
+/**
+ * Hook for persisting panel layouts across sessions
+ *
+ * Manages panel sizes and collapsed states with automatic debounced saving.
+ * Supports both 2-panel and 3-panel layouts.
+ *
+ * @param options - Configuration options for persistence
+ * @returns Panel state and handlers for resizing and collapsing
+ *
+ * @example
+ * ```tsx
+ * const persistence = usePanelPersistence({
+ *   viewKey: 'my-app',
+ *   defaultSizes: { left: 30, middle: 70, right: 0 },
+ *   collapsed: { left: false, right: true },
+ *   panelType: 'three-panel',
+ * });
+ *
+ * <ConfigurablePanelLayout
+ *   {...otherProps}
+ *   defaultSizes={persistence.sizes}
+ *   collapsed={persistence.collapsed}
+ *   onPanelResize={persistence.handlePanelResize}
+ * />
+ * ```
+ */
+export declare function usePanelPersistence(options: UsePanelPersistenceOptions): PanelPersistence;
+
+/**
+ * Configuration options for the usePanelPersistence hook
+ */
+export declare interface UsePanelPersistenceOptions {
+    /** Unique key for this view's persistence (e.g., 'feedView', 'codeReview') */
+    viewKey: string;
+    /** Default panel sizes to use if no saved state exists */
+    defaultSizes: PanelSizes | TwoPanelSizes;
+    /** Initial collapsed state for panels */
+    collapsed: PanelCollapsed | {
+        left?: boolean;
+    };
+    /** Whether this is a two-panel or three-panel layout */
+    panelType: 'three-panel' | 'two-panel';
+    /** Optional persistence adapter (defaults to localStorage) */
+    adapter?: PersistenceAdapter;
+}
+
+export declare function useWorkspace(options?: UseWorkspaceOptions): UseWorkspaceReturn;
+
+export declare interface UseWorkspaceOptions {
+    /**
+     * Optional repository key for repository-specific state
+     * If provided, the hook will manage repository state
+     */
+    repositoryKey?: string;
+    /**
+     * Auto-initialize repository state if it doesn't exist
+     */
+    autoInitialize?: boolean;
+    /**
+     * Default workspace to use for auto-initialization
+     */
+    defaultWorkspaceId?: string;
+}
+
+export declare interface UseWorkspaceReturn {
+    /**
+     * All available workspaces (built-in + user-created)
+     */
+    workspaces: Record<string, WorkspaceLayout>;
+    /**
+     * Current repository state (if repositoryKey provided)
+     */
+    repositoryState: RepositoryWorkspaceState | null;
+    /**
+     * Current active workspace (if repositoryKey provided)
+     */
+    activeWorkspace: WorkspaceLayout | null;
+    /**
+     * Loading state
+     */
+    loading: boolean;
+    /**
+     * Error state
+     */
+    error: Error | null;
+    /**
+     * Get a specific workspace by ID
+     */
+    getWorkspace: (id: string) => Promise<WorkspaceLayout | null>;
+    /**
+     * Create a new workspace
+     */
+    createWorkspace: (options: CreateWorkspaceOptions) => Promise<WorkspaceLayout>;
+    /**
+     * Update an existing workspace
+     */
+    updateWorkspace: (id: string, updates: UpdateWorkspaceOptions) => Promise<WorkspaceLayout | null>;
+    /**
+     * Delete a workspace
+     */
+    deleteWorkspace: (id: string) => Promise<boolean>;
+    /**
+     * Apply a workspace to the current repository
+     */
+    applyWorkspace: (workspaceId: string) => Promise<void>;
+    /**
+     * Update repository sizes
+     */
+    updateSizes: (sizes: {
+        left: number;
+        middle: number;
+        right: number;
+    }) => Promise<void>;
+    /**
+     * Update repository collapsed state
+     */
+    updateCollapsed: (collapsed: {
+        left?: boolean;
+        right?: boolean;
+    }) => Promise<void>;
+    /**
+     * Reset repository to workspace defaults
+     */
+    resetToDefaults: () => Promise<void>;
+    /**
+     * Refresh workspace data
+     */
+    refresh: () => Promise<void>;
+}
+
+/**
+ * WorkspaceLayout - A saved panel configuration preset
+ */
+export declare interface WorkspaceLayout {
+    /** Unique identifier for the workspace */
+    id: string;
+    /** Display name for the workspace */
+    name: string;
+    /** Optional description of the workspace's purpose */
+    description?: string;
+    /** Panel layout configuration */
+    layout: PanelLayout;
+    /** Default panel sizes (percentages) */
+    defaultSizes?: {
+        left: number;
+        middle: number;
+        right: number;
+    };
+    /** Default collapsed state for panels */
+    defaultCollapsed?: {
+        left?: boolean;
+        right?: boolean;
+    };
+    /** Creation timestamp */
+    createdAt: number;
+    /** Last update timestamp */
+    updatedAt: number;
+    /** Whether this is a built-in workspace (cannot be modified/deleted) */
+    isBuiltIn?: boolean;
+}
+
+export declare class WorkspaceLayoutService {
+    private static adapter;
+    /**
+     * Configure a custom storage adapter (for Electron IPC or remote storage)
+     */
+    static setAdapter(adapter: WorkspaceStorageAdapter): void;
+    /**
+     * Get all workspace layouts (including built-in)
+     */
+    static getWorkspaceLayouts(): Promise<Record<string, WorkspaceLayout>>;
+    /**
+     * Get a specific workspace layout by ID
+     */
+    static getWorkspaceLayout(id: string): Promise<WorkspaceLayout | null>;
+    /**
+     * Create a new workspace layout
+     */
+    static createWorkspaceLayout(options: CreateWorkspaceOptions): Promise<WorkspaceLayout>;
+    /**
+     * Update an existing workspace layout
+     */
+    static updateWorkspaceLayout(id: string, updates: UpdateWorkspaceOptions): Promise<WorkspaceLayout | null>;
+    /**
+     * Delete a workspace layout
+     */
+    static deleteWorkspaceLayout(id: string): Promise<boolean>;
+    /**
+     * Get repository state (which workspace + current sizes/collapsed)
+     */
+    static getRepositoryState(repositoryKey: string): Promise<RepositoryWorkspaceState | null>;
+    /**
+     * Set repository state (which workspace + current sizes/collapsed/layout)
+     */
+    static setRepositoryState(repositoryKey: string, state: RepositoryWorkspaceState): Promise<void>;
+    /**
+     * Update only sizes in repository state
+     */
+    static updateRepositorySizes(repositoryKey: string, sizes: {
+        left: number;
+        middle: number;
+        right: number;
+    }): Promise<void>;
+    /**
+     * Update only collapsed state in repository state
+     */
+    static updateRepositoryCollapsed(repositoryKey: string, collapsed: {
+        left?: boolean;
+        right?: boolean;
+    }): Promise<void>;
+    /**
+     * Check if repository state differs from workspace defaults
+     */
+    static hasStateDeviation(repoState: {
+        workspaceId: string | null;
+        sizes: {
+            left: number;
+            middle: number;
+            right: number;
+        };
+        collapsed: {
+            left?: boolean;
+            right?: boolean;
+        };
+    }, workspace: WorkspaceLayout): {
+        hasSizeDeviation: boolean;
+        hasCollapsedDeviation: boolean;
+    };
+    /**
+     * Update workspace defaults from repository state
+     */
+    static updateWorkspaceFromRepositoryState(workspaceId: string, repositoryKey: string): Promise<void>;
+    /**
+     * Reset repository state to workspace defaults
+     */
+    static resetRepositoryToWorkspaceDefaults(repositoryKey: string, workspaceId: string): Promise<void>;
+    /**
+     * Check if a layout matches a workspace layout
+     */
+    static isLayoutMatchingWorkspace(layout: PanelLayout, workspace: WorkspaceLayout): boolean;
+    /**
+     * Find workspace ID that matches the given layout
+     */
+    static findMatchingWorkspace(layout: PanelLayout): Promise<string | null>;
+    /**
+     * Deep comparison of two panel layouts
+     */
+    private static areLayoutsEqual;
+    /**
+     * Generate a unique ID from a workspace name
+     */
+    private static generateWorkspaceId;
+    /**
+     * Get built-in workspace layouts
+     */
+    static getBuiltInWorkspaceLayouts(): Record<string, WorkspaceLayout>;
+    /**
+     * Initialize workspace layouts with built-in defaults if none exist
+     */
+    static initializeWorkspaceLayouts(): Promise<void>;
+}
+
+export declare type WorkspacePreset = WorkspaceLayout;
+
+/**
+ * Storage interface for workspace data
+ * Implementations can use localStorage, Electron IPC, or remote storage
+ */
+export declare interface WorkspaceStorageAdapter {
+    /**
+     * Load all user-created workspace presets
+     */
+    loadWorkspacePresets(): Promise<Record<string, WorkspaceLayout>>;
+    /**
+     * Save workspace presets
+     */
+    saveWorkspacePresets(presets: Record<string, WorkspaceLayout>): Promise<void>;
+    /**
+     * Load repository-specific workspace state
+     */
+    loadRepositoryState(repositoryKey: string): Promise<RepositoryWorkspaceState | null>;
+    /**
+     * Save repository-specific workspace state
+     */
+    saveRepositoryState(repositoryKey: string, state: RepositoryWorkspaceState): Promise<void>;
+    /**
+     * Load all repository states
+     */
+    loadAllRepositoryStates(): Promise<Record<string, RepositoryWorkspaceState>>;
+}
+
+export { }