pipeworks_mud_mapper.callbacks.exit_callbacks
=============================================

.. py:module:: pipeworks_mud_mapper.callbacks.exit_callbacks

.. autoapi-nested-parse::

   Exit management callbacks.

   This module handles both:

   - Local exit checkbox changes (bidirectional exits within a zone)
   - Cross-zone exit edits via the Workspace table/editor (zone_id:room_id)

   Design Decisions
   ----------------
   **Bidirectional by default**: When an exit checkbox is checked and a
   target room is found, both the forward and reverse exits are created.
   This matches player expectations in MUDs.

   **No room = rejected**: If no room exists in the checked direction,
   the checkbox is automatically unchecked and a warning is shown.

   **Removal is one-way**: When unchecking an exit, only the exit from
   the current room is removed. The reverse exit on the target room
   remains (can be manually removed if needed).

   Component Dependencies
   ----------------------
   **Inputs:**
   - ``exit-checkboxes``: Checklist of direction abbreviations
   - ``workspace-zone-exit-direction``: Selected direction for zone exits
   - ``workspace-zone-exit-zone``: Selected zone for cross-zone exit
   - ``workspace-zone-exit-room``: Selected room for cross-zone exit
   - ``workspace-zone-exit-save``: Persist the zone exit selection
   - ``workspace-zone-exit-clear``: Remove a zone exit from a direction

   **States:**
   - ``selected-room``: Currently selected room
   - ``current-zone-data``: Zone data for room lookup + mutation

   **Outputs:**
   - ``current-zone-data``: Updated with new exits
   - ``exit-checkboxes``: Corrected values (rejected unchecked)
   - ``exit-feedback``: Status display
   - ``workspace-zone-exit-table``: Zone exit summary table
   - ``workspace-zone-exit-feedback``: Status display for cross-zone exits
   - ``has-unsaved-changes``: Unsaved flag

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



Functions
---------

.. autoapisummary::

   pipeworks_mud_mapper.callbacks.exit_callbacks.handle_exit_changes
   pipeworks_mud_mapper.callbacks.exit_callbacks.load_workspace_zone_exit_zone_options
   pipeworks_mud_mapper.callbacks.exit_callbacks.update_workspace_zone_exit_room_options
   pipeworks_mud_mapper.callbacks.exit_callbacks.update_workspace_zone_exit_table
   pipeworks_mud_mapper.callbacks.exit_callbacks.populate_workspace_zone_exit_editor
   pipeworks_mud_mapper.callbacks.exit_callbacks.clear_workspace_zone_exit_feedback
   pipeworks_mud_mapper.callbacks.exit_callbacks.handle_workspace_zone_exit_action


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

.. py:function:: handle_exit_changes(checked_values, selected_room, zone_data)

   Handle exit checkbox changes - add or remove exits.

   When an exit checkbox is checked:

   1. Find the nearest room in that direction
   2. If found, create exit and reverse exit (bidirectional)
   3. If not found, reject and show warning

   When an exit checkbox is unchecked:

   1. Remove the exit from current room only
   2. Reverse exit on target room is NOT removed (can be done manually)

   :param checked_values: List of checked direction abbreviations (e.g., ["N", "E"]).
   :type checked_values: :py:class:`list[str]`
   :param selected_room: Currently selected room ID.
   :type selected_room: :py:class:`str | None`
   :param zone_data: Current zone data.
   :type zone_data: :py:class:`dict | None`

   :returns: Updated zone data, corrected checkbox values, feedback, unsaved flag.
   :rtype: :py:class:`tuple`

   .. admonition:: Notes

      - Uses find_room_in_direction to locate nearest room
      - OPPOSITE_DIRECTION maps direction to its reverse
      - Rejected directions (no room found) are unchecked automatically
      - Feedback shows current exits and any warnings


.. py:function:: load_workspace_zone_exit_zone_options(_)

   Load zone options from world metadata for the workspace editor.


.. py:function:: update_workspace_zone_exit_room_options(zone_id, current_room)

   Update room options when the selected zone changes.


.. py:function:: update_workspace_zone_exit_table(selected_room, zone_data)

   Render the zone exit table for the selected room.


.. py:function:: populate_workspace_zone_exit_editor(selected_room, row_clicks, zone_data)

   Populate the zone exit editor from table clicks.


.. py:function:: clear_workspace_zone_exit_feedback(_)

   Clear action feedback when the selected room changes.


.. py:function:: handle_workspace_zone_exit_action(save_clicks, clear_clicks, direction_short, zone_id, room_id, selected_room, zone_data)

   Apply workspace zone exit changes to the active map.