-- ============================================================================
-- HDG_signatures.lua - API Reference
-- HousingDecorGuide Public Function Signatures
-- Auto-generated reference - do not execute, documentation only
-- ============================================================================

-- ============================================================================
-- HDG_Core.lua - Global Namespace
-- ============================================================================
-- HousingDecorGuide = {} -- Global addon table (defined in HDG_Core.lua)

-- ============================================================================
-- HDG_Config.lua - Constants, Settings, Logging
-- ============================================================================
-- privateDB.CONFIG                                 -- Configuration constants table (sizes, colors, textures)
-- privateDB.Log(level, message, ...)               -- Internal logging with LOG_LEVEL filter
-- privateDB.LOG_LEVEL                              -- { DEBUG=1, INFO=2, WARN=3, ERROR=4 }
-- privateDB.ValidateSettings()                     -- Validate/initialize HDG_Settings with defaults
-- privateDB.MigrateToStore()                       -- Migrate legacy HDG_Settings to HDG_DB (Store)
-- privateDB.CreateSettingsProxy()                  -- Create backward-compat proxy for HDG_Settings
-- privateDB.InitSettingsProxy()                    -- Initialize settings proxy after Store ready

-- ============================================================================
-- HDG_Data.lua - Recipe/Collection Data Access
-- ============================================================================
HDG_Data.GetReagentInfo(itemID)                     -- Parse ReagentsDB entry -> { source, vendorPrice, canBuy }
HDG_Data.GetCachedItemName(itemID)                  -- Get item name (cached, async loads if needed)
HDG_Data.GetLocalizedName(itemID, fallbackName)     -- Get localized name, prefer WoW API
HDG_Data.IsItemCollected(itemID)                    -- Check if decor item is collected (by itemID)
HDG_Data.IsDecorCollected(decorID)                  -- Check if decor is collected (by decorID)
HDG_Data.MarkDecorCollected(decorID)                -- Force-mark decor as collected (bypasses API delay)
HDG_Data.ClearCaches()                              -- Clear item name and collection caches
HDG_Data.GetItemCount(itemID)                       -- Get total item count (bags+bank+warband)
HDG_Data.GetItemCountWithVariants(itemID)           -- Get count including all quality variants (R1+R2+R3)
HDG_Data.GetPersonalItemCount(itemID)               -- Get count excluding Warband Bank
HDG_Data.GetWarbandBankCount(itemID)                -- Get count in Warband Bank only
HDG_Data.SaveCharacterLumberInventory()             -- Save current char's lumber to Store
HDG_Data.GetAccountWideLumberCount(lumberId)        -- Get account-wide lumber total + breakdown
HDG_Data.GetLumberBreakdown(lumberId)               -- Get per-character lumber breakdown
HDG_Data.PlayerKnowsRecipeBySpellID(spellID)        -- Check if player knows recipe (by spellID)
HDG_Data.BuildKnownRecipeCache()                    -- Build cache of known recipe spellIDs
HDG_Data.InvalidateRecipeCache()                    -- Clear known recipe cache
HDG_Data.PlayerKnowsRecipe(recipeName)              -- Check if player knows recipe (by name, legacy)
HDG_Data.GetRecipeSpellID(recipeName)               -- Get spellID for a recipe name
HDG_Data.PlayerHasProfession(professionName)        -- Check if player has profession
HDG_Data.OpenProfessionAtRecipe(professionName, recipeSpellID) -- Open profession window at recipe
HDG_Data.GetPlayerProfessions()                     -- Get player professions for UI display
HDG_Data.InitializeDatabase()                       -- Transform HDG_DecorDB into addon format
HDG_Data.CalculateLumberNeeds(professions)          -- Calculate lumber needs for all recipes
HDG_Data.CalculateShoppingListLumber(shoppingList)  -- Calculate lumber for shopping list
HDG_Data.GetItemPrice(itemID)                       -- Delegate to HDG_PriceIntegration
HDG_Data.FormatGold(copper, useTextures)            -- Delegate to HDG_PriceIntegration
HDG_Data.HasPriceAddon()                            -- Delegate to HDG_PriceIntegration
HDG_Data.LogCraftIfDecor(spellID)                   -- Log craft if decor recipe (legacy)
HDG_Data.LogCraftFromItemLink(itemLink, quantity)   -- Log craft from item link
HDG_Data.GetCraftingHistory()                       -- Get crafting history
HDG_Data.ClearCraftingHistory()                     -- Clear crafting history
HDG_Data.FormatTimestamp(timestamp)                 -- Format timestamp for display
HDG_Data.CanCraftRecipe(recipe)                     -- Check if player can craft recipe
HDG_Data.GetCraftableRecipes(professionFilter)      -- Get all craftable recipes
HDG_Data.IsCraftableFilterEnabled()                 -- Check if "What Can I Craft" mode enabled
HDG_Data.SetCraftableFilter(enabled)                -- Toggle "What Can I Craft" mode
HDG_Data.GetCharacterKey()                          -- Get unique character key (Name-Realm)
HDG_Data.CollectCharacterProfessions()              -- Collect/cache current char's professions
HDG_Data.GetAltProfessionData(professionName)       -- Get alt profession data
HDG_Data.GetBestAltRecipeCount(professionName)      -- Get best alt's recipe count
HDG_Data.AnyAltHasProfession(professionName)        -- Check if any alt has profession
HDG_Data.GetCharactersWhoKnowRecipe(spellID, professionName) -- Get chars who know recipe

-- ============================================================================
-- HDG_UI.lua - Main Window Management
-- ============================================================================
HDG_UI.CreateUI()                                   -- Create main addon window
HDG_UI.Toggle()                                     -- Toggle main window visibility
HDG_UI.OpenWithProfession(professionName)           -- Open filtered to specific profession
HDG_UI.RefreshUI()                                  -- Refresh all visible UI elements
HDG_UI.UpdateTabs()                                 -- Update tab states and visibility
HDG_UI.CountKnownRecipes(profData)                  -- Count known recipes in profession
HDG_UI.CreateTrainersPanel()                        -- Create trainers placeholder frame
HDG_UI.RefreshCharactersPanel()                     -- Refresh characters/alts panel
HDG_UI.UpdateLumberLayout()                         -- Update lumber panel (embedded vs pinned)
HDG_UI.RefreshEmbeddedLumber()                      -- Refresh embedded lumber content
HDG_UI.RefreshLumberTracking()                      -- Refresh all lumber displays
HDG_UI.RefreshProfessionTabs()                      -- Delegate: refresh profession tabs
HDG_UI.AddToShoppingList(recipe, skipRefresh)       -- Delegate: add recipe to shopping list
HDG_UI.RefreshShoppingList()                        -- Delegate: refresh shopping list panel
HDG_UI.RefreshMaterials()                           -- Delegate: refresh materials panel
HDG_UI.AddAllMaterialsToAuctionator()               -- Delegate: add mats to Auctionator search
HDG_UI.UpdateProfessionButtonVisibility()           -- Update profession window button visibility
HDG_UI.RefreshQuote()                               -- Refresh random Orc quote
HDG_UI.RequestHouseInfo()                           -- Request house info (async)
HDG_UI.OnHouseListUpdated(houseInfoList)            -- Handler for PLAYER_HOUSE_LIST_UPDATED
HDG_UI.OnHouseLevelFavorUpdated(houseLevelFavor)    -- Handler for HOUSE_LEVEL_FAVOR_UPDATED
HDG_UI.UpdateHouseLevelDisplay()                    -- Update house level display

-- ============================================================================
-- HDG_UIHelpers.lua - UI Utilities
-- ============================================================================
HDG_UIHelpers.GetScheme()                           -- Get current color scheme from Theme Engine
HDG_UIHelpers.RegisterWidget(widget, widgetType)    -- Register widget with Theme Engine
HDG_UIHelpers.ColorText(text, colorKey)             -- Apply color code to text
HDG_UIHelpers.GetBorderColor(alpha)                 -- Get scheme-aware border color
HDG_UIHelpers.GetActiveColor(alpha)                 -- Get scheme-aware active state color
HDG_UIHelpers.GetInactiveColor(alpha)               -- Get scheme-aware inactive state color
HDG_UIHelpers.GetHoverColor(alpha)                  -- Get scheme-aware hover color
HDG_UIHelpers.GetTextColor(isDim, isHeader)         -- Get scheme-aware text color
HDG_UIHelpers.GetAccentColor(alpha)                 -- Get scheme-aware accent color
HDG_UIHelpers.GetPanelColor(alpha)                  -- Get scheme-aware panel background color
HDG_UIHelpers.GetBgColor(alpha)                     -- Get scheme-aware main background color
HDG_UIHelpers.GetProgressBarColor(percentage)       -- Get teal gradient color for progress bars
HDG_UIHelpers.ApplyBackdrop(frame, backdropType, bgColor, borderColor) -- Apply predefined backdrop
HDG_UIHelpers.SetupTooltip(frame, title, description, anchor) -- Setup standard tooltip
HDG_UIHelpers.SetupItemTooltip(frame, itemID, extraLines, anchor) -- Setup item tooltip
HDG_UIHelpers.SetupHoverEffect(frame, normalColor, hoverColor, textElement, normalTextColor, hoverTextColor) -- Setup hover colors
HDG_UIHelpers.SetupHoverWithTooltip(frame, normalColor, hoverColor, tooltipTitle, tooltipDesc, anchor) -- Combined hover+tooltip
HDG_UIHelpers.CreateSectionHeader(parent, text, yOffset, colorKey) -- Create section header
HDG_UIHelpers.CreateLeftHeader(parent, text, xOffset, yOffset, colorKey) -- Create left-aligned header
HDG_UIHelpers.CreateFilterButton(parent, text, width, isActive, onClick, options) -- Create filter button
HDG_UIHelpers.CreatePanel(parent, config)           -- Create standard panel frame
HDG_UIHelpers.ClearScrollContent(scrollContent)     -- Clear all children from scroll content
HDG_UIHelpers.FormatGold(copper, useTextures)       -- Format copper as gold string
HDG_UIHelpers.PrintMessage(message, messageType)    -- Print addon message with formatting
HDG_UIHelpers.StyleScrollBar(scrollFrame, thumbColor, trackColor) -- Style scrollbar minimalist
HDG_UIHelpers.CreateLumberRow(parent, lumberId, lumberInfo, shoppingData, allData, yOffset, farmingOptions) -- Create lumber tracking row
HDG_UIHelpers.Data()                                -- Nil-safe accessor for HDG_Data module

-- ============================================================================
-- HDG_RecipesTab.lua - Recipes/Shopping/Materials Panels
-- ============================================================================
HDG_RecipesTab.GetProfessionFilter()                -- Get per-character profession filter
HDG_RecipesTab.SetProfessionFilter(professionName)  -- Set per-character profession filter
HDG_RecipesTab.AggregateMaterials(shoppingList)     -- Aggregate direct materials from shopping list
HDG_RecipesTab.AggregateRawMaterials(shoppingList)  -- Aggregate raw materials (expands crafted)
HDG_RecipesTab.FilterAndSortMaterials(materials)    -- Filter and sort material list
HDG_RecipesTab.CategorizeMaterials(matArray)        -- Categorize materials by source type
HDG_RecipesTab.CanCraftRecipe(recipe)               -- Check if player can craft recipe now
HDG_RecipesTab.ShowCraftConfirmation(item, shoppingListIndex) -- Show craft confirmation dialog
HDG_RecipesTab.ExecuteCraft(item, shoppingListIndex, quantity) -- Execute crafting
HDG_RecipesTab.GetCraftableRecipes(professionFilter) -- Get all craftable recipes
HDG_RecipesTab.IsCraftableFilterEnabled()           -- Check if "What Can I Craft" enabled
HDG_RecipesTab.SetCraftableFilter(enabled)          -- Toggle "What Can I Craft" mode
HDG_RecipesTab.GetSearchFilter()                    -- Get current search text
HDG_RecipesTab.SetSearchFilter(text)                -- Set search filter text
HDG_RecipesTab.IsSearchReagentsEnabled()            -- Check if searching reagents too
HDG_RecipesTab.SetSearchReagents(enabled)           -- Toggle searching reagent names
HDG_RecipesTab.IsUncollectedFilterEnabled()         -- Check if uncollected-only filter enabled
HDG_RecipesTab.SetUncollectedFilter(enabled)        -- Toggle uncollected-only filter
HDG_RecipesTab.RecipeMatchesFilters(recipe)         -- Check if recipe passes all filters
HDG_RecipesTab:Init(frame)                          -- Initialize module with mainFrame
HDG_RecipesTab:CreateRecipePanel()                  -- Create recipe list panel
HDG_RecipesTab:CreateShoppingPanel()                -- Create shopping list panel
HDG_RecipesTab:CreateMaterialsPanel()               -- Create materials panel
HDG_RecipesTab:Create()                             -- Create all three panels
HDG_RecipesTab:AddToShoppingList(recipe, skipRefresh) -- Add recipe to shopping list
HDG_RecipesTab:RefreshShoppingList()                -- Refresh shopping list display
HDG_RecipesTab:RefreshMaterials()                   -- Refresh materials display
HDG_RecipesTab:AddAllMaterialsToAuctionator()       -- Add all materials to Auctionator search
HDG_RecipesTab:RefreshProfessionTabs()              -- Refresh profession tab buttons
HDG_RecipesTab:RefreshRecipes()                     -- Refresh recipe list
HDG_RecipesTab:Refresh()                            -- Refresh all tab content
HDG_RecipesTab:Show()                               -- Show recipes tab panels
HDG_RecipesTab:Hide()                               -- Hide recipes tab panels

-- ============================================================================
-- HDG_PowerCrafting.lua - DAG-Based Recipe Resolution
-- ============================================================================
HDG_PowerCrafting.GetRecipeByItemID(itemID)         -- Get recipe entry by output itemID
HDG_PowerCrafting.GetAllRecipesForItem(itemID)      -- Get ALL recipes that produce itemID
HDG_PowerCrafting.IsCraftedReagent(itemID)          -- Check if item is a crafted reagent
HDG_PowerCrafting.GetCraftedRecipe(itemID)          -- Get recipe for crafted item (basic slots only)
HDG_PowerCrafting.BuildDependencyGraph(decorRecipe) -- Build dependency graph for recipe
HDG_PowerCrafting.TopologicalSort(graph)            -- Kahn's algorithm for crafting order
HDG_PowerCrafting.CalculateRawMaterials(shoppingList) -- Get total raw materials for queue
HDG_PowerCrafting.GetCraftingOrder(decorRecipe)     -- Get ordered crafting steps
HDG_PowerCrafting.GetItemName(itemID)               -- Get item name with fallbacks
HDG_PowerCrafting.CanPlayerCraft(itemID)            -- Check if player can craft item (stub)
HDG_PowerCrafting.GetMaterialBreakdown(decorRecipe) -- Get detailed material breakdown

-- ============================================================================
-- HDG_PriceIntegration.lua - TSM/Auctionator Integration
-- ============================================================================
HDG_PriceIntegration.GetItemPrice(itemID, forceAddon) -- Get market price (TSM or Auctionator)
HDG_PriceIntegration.FormatGold(copper, useTextures) -- Format copper as gold string
HDG_PriceIntegration.FormatGoldOnly(copper)         -- Format as gold-only with commas
HDG_PriceIntegration.HasPriceAddon()                -- Check if any price addon available
HDG_PriceIntegration.IsTSMAvailable()               -- Check if TSM is available
HDG_PriceIntegration.IsAuctionatorAvailable()       -- Check if Auctionator is available
HDG_PriceIntegration.GetAvailableAddons()           -- Get list of available price addons
HDG_PriceIntegration.GetActiveAddon()               -- Get name of active price addon
HDG_PriceIntegration.GetRegionSaleAvg(itemID)       -- Get TSM region sale average
HDG_PriceIntegration.CalculateTotalPrice(materials) -- Calculate total price for material list
