better comments on floating panel

Author: MaxITService

floating-panel-settings.js

@@ -5,6 +5,33 @@
 // This file handles settings persistence and profile management for the floating panel.
 // It includes methods for loading/saving panel settings, debouncing saves, and profile switching.
 // These functions extend the window.MaxExtensionFloatingPanel namespace.
+//
+// Key Components:
+// 1. Settings Management - Loading and saving panel configuration per website
+// 2. Storage Integration - Communication with the config.js service worker
+// 3. Profile Management - Loading available profiles and handling profile switching
+// 4. Initialization - Setup of the floating panel system
+//
+// Key Methods:
+// - loadPanelSettings(): Fetches settings from service worker for current hostname
+// - savePanelSettings(): Stores current panel settings via service worker
+// - debouncedSavePanelSettings(): Throttles saves to improve performance
+// - loadAvailableProfiles(): Gets profile list from service worker
+// - getCurrentProfile(): Fetches and sets current active profile
+// - switchToProfile(): Changes active profile and updates panel content
+// - initialize(): Sets up the floating panel (creates UI and loads settings)
+//
+// Implementation Details:
+// - All settings are stored with the prefix 'floating_panel_' followed by hostname
+// - Settings are loaded asynchronously via chrome.runtime.sendMessage
+// - The panel uses a debounce mechanism (150ms) to avoid excessive storage writes
+// - Each website has its own panel settings (position, size, visibility)
+// - Profile switching refreshes the buttons shown in the panel
+//
+// Dependencies:
+// - floating-panel.js: Provides the namespace and shared properties
+// - floating-panel-ui.js: Provides UI update methods
+// - config.js (Service Worker): Handles persistent storage operations
 
 'use strict';
 

floating-panel-ui.js

@@ -5,6 +5,33 @@
 // This file contains all UI-related functionality for the floating panel,
 // including creation, layout, drag behavior, and button moving logic.
 // It extends the window.MaxExtensionFloatingPanel namespace with the corresponding methods.
+//
+// Key Components:
+// 1. Panel Creation - Creates the panel with header, content area, and profile switcher
+// 2. Drag Behavior - Makes the panel draggable by the header or footer
+// 3. Panel Visibility - Toggles the panel and handles state persistence
+// 4. Button Movement - Moves buttons between the original container and floating panel
+// 5. Profile Switching UI - Creates and manages the profile dropdown in the panel footer
+//
+// Key Methods:
+// - createFloatingPanel(): Creates the panel DOM structure with styling
+// - makeDraggable(): Adds drag functionality to specified elements
+// - togglePanel(): Handles panel visibility toggling and button movement
+// - moveButtonsToPanel(): Moves buttons from their original container to the panel
+// - restorePanelState(): Ensures panel visibility matches saved settings
+// - positionPanelAtCursor(): Positions the panel relative to mouse cursor
+// - createPanelToggleButton(): Creates the button that summons the floating panel
+//
+// Known Issues & Fixes:
+// - The togglePanel() method avoids loadPanelSettings() when initially creating the panel
+//   to prevent race conditions that could cause the panel to disappear after summoning
+// - restorePanelState() only toggles the panel if its current state doesn't match the desired state
+//   to prevent unintended toggling when loading settings
+//
+// Dependencies:
+// - floating-panel.js: Provides the namespace and shared properties
+// - floating-panel-settings.js: Provides settings management methods
+// - utils.js: For logging functionality
 
 'use strict';
 

floating-panel.js

@@ -5,6 +5,27 @@
 // This file implements the entry point for the OneClickPrompts floating panel.
 // It defines the window.MaxExtensionFloatingPanel namespace (with common properties)
 // and loads additional functionality split into two files: floating-panel-ui.js and floating-panel-settings.js.
+//
+// Structure:
+// 1. Namespace: window.MaxExtensionFloatingPanel - Global object containing all floating panel functionality
+// 2. Properties:
+//    - panelElement: Reference to the panel DOM element
+//    - isPanelVisible: Boolean tracking current visibility state
+//    - currentProfileName: Currently active profile name
+//    - availableProfiles: Array of all available profile names
+//    - storageKeyPrefix: Prefix used for storing settings ('floating_panel_')
+//    - defaultPanelSettings: Default configuration for new panels
+//    - currentPanelSettings: Current active settings for the panel
+//    - savePositionTimer: Used for debounced settings saves
+//
+// Dependencies:
+// - floating-panel-ui.js: Contains UI creation and interaction methods
+// - floating-panel-settings.js: Contains settings and profile management
+// - config.js (Service Worker): Handles persistent storage of panel settings
+//
+// Communication:
+// The floating panel uses chrome.runtime.sendMessage to communicate with the config.js
+// service worker for storing and retrieving settings based on the website hostname.
 // 
 // IMPORTANT: DO NOT REMOVE COMMENTS. All old names are preserved.