pipeworks_mud_mapper.callbacks.validation_callbacks
===================================================

.. py:module:: pipeworks_mud_mapper.callbacks.validation_callbacks

.. autoapi-nested-parse::

   Validation callbacks for PipeWorks MUD Mapper.

   This module provides callbacks for running validation checks on maps
   and displaying results in a modal dialog. It also writes validation reports
   to the data/validation/ directory for CI/CD and record-keeping purposes.

   Callbacks
   ---------
   ``update_validate_button_state``
       Enables/disables the Validate button based on whether a map is loaded.

   ``run_validation``
       Runs all validation checks, opens the results modal, writes report file.

   ``close_validation_modal``
       Closes the validation results modal.

   ``select_room_from_validation``
       Handles clicking on a room ID in validation results to select it on map.

   Validation Categories
   ---------------------
   The validation service checks for three categories of issues:

   **Connectivity**
       - Broken exit references (ERROR - blocks export)
       - Unreachable rooms from spawn (WARNING)
       - Dead-end rooms with no exits (INFO)

   **Consistency**
       - Asymmetric exits (INFO - may be intentional one-way doors)
       - Direction/coordinate mismatches (WARNING)

   **Language**
       - "Upper Landing" problem - vertical words in names that don't match
         the navigational direction (INFO)

   Severity Levels
   ---------------
   - **ERROR**: Must be fixed before export (broken references)
   - **WARNING**: Should be reviewed but may be intentional
   - **INFO**: Informational - worth noting but likely intentional

   .. seealso:: :py:obj:`-`, :py:obj:`-`, :py:obj:`-`



Functions
---------

.. autoapisummary::

   pipeworks_mud_mapper.callbacks.validation_callbacks.update_validate_button_state
   pipeworks_mud_mapper.callbacks.validation_callbacks.run_validation
   pipeworks_mud_mapper.callbacks.validation_callbacks.close_validation_modal
   pipeworks_mud_mapper.callbacks.validation_callbacks.select_room_from_validation


Module Contents
---------------

.. py:function:: update_validate_button_state(selected_file)

   Enable/disable the Validate button based on whether a map is loaded.

   The Validate button is enabled when a map file is loaded (selected-file
   is not None). This prevents users from attempting to validate when
   there's no data to check.

   :param selected_file: Currently selected map ID, or None if no map is loaded.
   :type selected_file: :py:class:`str` or :py:obj:`None`

   :returns: True to disable the button (no file), False to enable (file loaded).
   :rtype: :py:class:`bool`


.. py:function:: run_validation(n_clicks, zone_data, selected_file)

   Run validation checks and display results in modal.

   This callback:
   1. Converts the zone data to a MapFile model
   2. Runs all validation checks via validation_service
   3. Writes a validation report to data/validation/
   4. Opens the modal with formatted results

   :param n_clicks: Number of times the Validate button has been clicked.
   :type n_clicks: :py:class:`int` or :py:obj:`None`
   :param zone_data: Current zone data from the store.
   :type zone_data: :py:class:`dict` or :py:obj:`None`
   :param selected_file: Map ID of the currently selected map.
   :type selected_file: :py:class:`str` or :py:obj:`None`

   :returns: (modal_is_open, modal_body_children, validation_report_data)
             - modal_is_open: True to show the modal
             - modal_body_children: Formatted validation results
             - validation_report_data: Report dict for storage
   :rtype: :py:class:`tuple`


.. py:function:: close_validation_modal(n_clicks)

   Close the validation results modal.

   :param n_clicks: Number of times the Close button has been clicked.
   :type n_clicks: :py:class:`int` or :py:obj:`None`

   :returns: False to close the modal, or no_update if not clicked.
   :rtype: :py:class:`bool` or :py:class:`dash.no_update`


.. py:function:: select_room_from_validation(n_clicks_list, id_list)

   Handle clicking on a room ID in validation results.

   When a user clicks on a room ID in the validation results, this callback:
   1. Selects that room on the map
   2. Closes the validation modal so the user can see the room

   :param n_clicks_list: List of n_clicks values for all room links.
   :type n_clicks_list: :py:class:`list`
   :param id_list: List of ID dictionaries for all room links.
   :type id_list: :py:class:`list`

   :returns: (selected_room_id, modal_is_open)
             - selected_room_id: The room ID that was clicked
             - modal_is_open: False to close the modal
   :rtype: :py:class:`tuple`