FvgPanel

█ OVERVIEW


This library provides functionalities for creating and managing a display panel within a Pine Script™ indicator. Its primary purpose is to offer a structured way to present Fair Value Gap (FVG) information, specifically the nearest bullish and bearish FVG levels across different timeframes (Current, MTF, HTF), directly on the chart. The library handles the table's structure, header initialization, and dynamic cell content updates.



█ CONCEPTS


The core of this library revolves around presenting summarized FVG data in a clear, tabular format. Key concepts include:


FVG Data Aggregation and Display

The panel is designed to show at-a-glance information about the closest active FVG mitigation levels. It doesn't calculate these FVGs itself but relies on the main script to provide this data. The panel is structured with columns for timeframes (TF), Bullish FVGs, and Bearish FVGs, and rows for "Current" (LTF), "MTF" (Medium Timeframe), and "HTF" (High Timeframe).


The `panelData` User-Defined Type (UDT)

To facilitate the transfer of information to be displayed, the library defines a UDT named `panelData`. This structure is central to the library's operation and is designed to hold all necessary values for populating the panel's data cells for each relevant FVG. Its fields include:

• Price levels for the nearest bullish and bearish FVGs for LTF, MTF, and HTF (e.g., `nearestBullMitLvl`, `nearestMtfBearMitLvl`).
  
• Boolean flags to indicate if these FVGs are classified as "Large Volume" (LV) (e.g., `isNearestBullLV`, `isNearestMtfBearLV`).
  
• Color information for the background and text of each data cell, allowing for conditional styling based on the FVG's status or proximity (e.g., `ltfBullBgColor`, `mtfBearTextColor`).
  

The design of `panelData` allows the main script to prepare all display-related data and styling cues in one object, which is then passed to the `updatePanel` function for rendering. This separation of data preparation and display logic keeps the library focused on its presentation task.


Visual Cues and Formatting

• Price Formatting: Price levels are formatted to match the instrument's minimum tick size using an internal `formatPrice` helper function, ensuring consistent and accurate display.
  
• Large FVG Icon: If an FVG is marked as a "Large Volume" FVG in the `panelData` object, a user-specified icon (e.g., an emoji) is prepended to its price level in the panel, providing an immediate visual distinction.
  
• Conditional Styling: The background and text colors for each FVG level displayed in the panel can be individually controlled via the `panelData` object, enabling the main script to implement custom styling rules (e.g., highlighting the overall nearest FVG across all timeframes).
  
• Handling Missing Data: If no FVG data is available for a particular cell (i.e., the corresponding level in `panelData` is `na`), the panel displays "---" and uses a specified background color for "Not Available" cells.
  

█ CALCULATIONS AND USE


Using the `FvgPanel` typically involves a two-stage process: initialization and dynamic updates.


Step 1: Panel Creation

First, an instance of the panel table is created once, usually during the script's initial setup. This is done using the `createPanel` function.

1. Call `createPanel()` with parameters defining its position on the chart, border color, border width, header background color, header text color, and header text size.
   
2. This function initializes the table with three columns ("TF", "Bull FVG", "Bear FVG") and three data rows labeled "Current", "MTF", and "HTF", plus a header row.
   
3. Store the returned `table` object in a `var` variable to persist it across bars.
   

// Example:
var table infoPanel = na
if barstate.isfirst
    infoPanel := panel.createPanel(
         position.top_right,
         color.gray,
         1,
         color.new(color.gray, 50),
         color.white,
         size.small
       )

Step 2: Panel Updates

On each bar, or whenever the FVG data changes (typically on `barstate.islast` or `barstate.isrealtime` for efficiency), the panel's content needs to be refreshed. This is done using the `updatePanel` function.

1. Populate an instance of the `panelData` UDT with the latest FVG information. This includes setting the nearest bullish/bearish mitigation levels for LTF, MTF, and HTF, their LV status, and their desired background and text colors.
   
2. Call `updatePanel()`, passing the persistent `table` object (from Step 1), the populated `panelData` object, the icon string for LV FVGs, the default text color for FVG levels, the background color for "N/A" cells, and the general text size for the data cells.
   
3. The `updatePanel` function will then clear previous data and fill the table cells with the new values and styles provided in the `panelData` object.
   

// Example (inside a conditional block like 'if barstate.islast'):
var panelData fvgDisplayData = panelData.new()

// ... (logic to populate fvgDisplayData fields) ...
// fvgDisplayData.nearestBullMitLvl = ...
// fvgDisplayData.ltfBullBgColor = ...
// ... etc.

if not na(infoPanel)
    panel.updatePanel(
         infoPanel,
         fvgDisplayData,
         "🔥", // LV FVG Icon
         color.white,
         color.new(color.gray, 70), // NA Cell Color
         size.small
       )

This workflow ensures that the panel is drawn only once and its cells are efficiently updated as new data becomes available.



█ NOTES

• Data Source: This library is solely responsible for the visual presentation of FVG data in a table. It does not perform any FVG detection or calculation. The calling script must compute or retrieve the FVG levels, LV status, and desired styling to populate the `panelData` object.
  
• Styling Responsibility: While `updatePanel` applies colors passed via the `panelData` object, the logic for *determining* those colors (e.g., highlighting the closest FVG to the current price) resides in the calling script.
  
• Performance: The library uses `table.cell()` to update individual cells, which is generally more efficient than deleting and recreating the table on each update. However, the frequency of `updatePanel` calls should be managed by the main script (e.g., using `barstate.islast` or `barstate.isrealtime`) to avoid excessive processing on historical bars.
  
• `series float` Handling: The price level fields within the `panelData` UDT (e.g., `nearestBullMitLvl`) can accept `series float` values, as these are typically derived from price data. The internal `formatPrice` function correctly handles `series float` for display.
  
• Dependencies: The `FvgPanel` itself is self-contained and does not import other user libraries. It uses standard Pine Script™ table and string functionalities.
  

█ EXPORTED TYPES


panelData
  Represents the data structure for populating the FVG information panel.
  Fields:
    nearestBullMitLvl (series float): The price level of the nearest bullish FVG's mitigation point (bottom for bull) on the LTF.
    isNearestBullLV (series bool): True if the nearest bullish FVG on the LTF is a Large Volume FVG.
    ltfBullBgColor (series color): Background color for the LTF bullish FVG cell in the panel.
    ltfBullTextColor (series color): Text color for the LTF bullish FVG cell in the panel.
    nearestBearMitLvl (series float): The price level of the nearest bearish FVG's mitigation point (top for bear) on the LTF.
    isNearestBearLV (series bool): True if the nearest bearish FVG on the LTF is a Large Volume FVG.
    ltfBearBgColor (series color): Background color for the LTF bearish FVG cell in the panel.
    ltfBearTextColor (series color): Text color for the LTF bearish FVG cell in the panel.
    nearestMtfBullMitLvl (series float): The price level of the nearest bullish FVG's mitigation point on the MTF.
    isNearestMtfBullLV (series bool): True if the nearest bullish FVG on the MTF is a Large Volume FVG.
    mtfBullBgColor (series color): Background color for the MTF bullish FVG cell.
    mtfBullTextColor (series color): Text color for the MTF bullish FVG cell.
    nearestMtfBearMitLvl (series float): The price level of the nearest bearish FVG's mitigation point on the MTF.
    isNearestMtfBearLV (series bool): True if the nearest bearish FVG on the MTF is a Large Volume FVG.
    mtfBearBgColor (series color): Background color for the MTF bearish FVG cell.
    mtfBearTextColor (series color): Text color for the MTF bearish FVG cell.
    nearestHtfBullMitLvl (series float): The price level of the nearest bullish FVG's mitigation point on the HTF.
    isNearestHtfBullLV (series bool): True if the nearest bullish FVG on the HTF is a Large Volume FVG.
    htfBullBgColor (series color): Background color for the HTF bullish FVG cell.
    htfBullTextColor (series color): Text color for the HTF bullish FVG cell.
    nearestHtfBearMitLvl (series float): The price level of the nearest bearish FVG's mitigation point on the HTF.
    isNearestHtfBearLV (series bool): True if the nearest bearish FVG on the HTF is a Large Volume FVG.
    htfBearBgColor (series color): Background color for the HTF bearish FVG cell.
    htfBearTextColor (series color): Text color for the HTF bearish FVG cell.



█ EXPORTED FUNCTIONS


createPanel(position, borderColor, borderWidth, headerBgColor, headerTextColor, headerTextSize)
  Creates and initializes the FVG information panel (table). Sets up the header rows and timeframe labels.
  Parameters:
    position (simple string): The position of the panel on the chart (e.g., position.top_right). Uses position.* constants.
    borderColor (simple color): The color of the panel's border.
    borderWidth (simple int): The width of the panel's border.
    headerBgColor (simple color): The background color for the header cells.
    headerTextColor (simple color): The text color for the header cells.
    headerTextSize (simple string): The text size for the header cells (e.g., size.small). Uses size.* constants.
  Returns: The newly created table object representing the panel.


updatePanel(panelTable, data, lvIcon, defaultTextColor, naCellColor, textSize)
  Updates the content of the FVG information panel with the latest FVG data.
  Parameters:
    panelTable (table): The table object representing the panel to be updated.
    data (panelData): An object containing the FVG data to display.
    lvIcon (simple string): The icon (e.g., emoji) to display next to Large Volume FVGs.
    defaultTextColor (simple color): The default text color for FVG levels if not highlighted.
    naCellColor (simple color): The background color for cells where no FVG data is available ("---").
    textSize (simple string): The text size for the FVG level data (e.g., size.small).
  Returns: _void